Kordant/tasks/core-services-implementation/14-family-plans.md

14. Family Plan Member Management, Billing Proration, and Multi-User Dashboard

meta: id: core-services-14 feature: core-services-implementation priority: P2 depends_on: [core-services-01] tags: [billing, family-plans, multi-user, proration, dashboard, member-management]

objective:

• Implement family plan support: invite family members, manage their access, prorate billing on member changes, and provide a multi-user dashboard showing consolidated family security status.

deliverables:

• Family member invitation system (email invites with acceptance flow)
• Role-based access control (primary account holder vs. member)
• Billing proration for adding/removing family members mid-cycle
• Family dashboard showing all members' threat scores and alerts
• Per-member service configuration (what each member monitors)

steps:

1. Extend database schema:
   • Add familyGroups table: id, primaryUserId, planTier, maxMembers, createdAt
   • Add familyMembers table: id, familyGroupId, userId, role (primary/member), status (pending/active/removed), invitedAt, joinedAt
   • Add familyInvitations table: id, familyGroupId, email, token, expiresAt, acceptedAt
2. Implement invitation flow:
   • Primary user sends invite by email → generates signed token
   • Invitee clicks link → creates account (if new) or links existing account
   • Invitation expires after 7 days
   • Send reminder email after 3 days if not accepted
3. Implement member management:
   • Primary user can view all members, their active services, and threat scores
   • Primary user can remove members (prorated refund or credit)
   • Members can leave family group voluntarily
   • Members cannot see other members' sensitive data (SSN, specific breach details)
4. Implement billing proration:
   • Add member mid-cycle: charge prorated amount for remaining days via Stripe
   • Remove member mid-cycle: credit prorated amount to account balance
   • Change plan tier: prorate difference, apply to next invoice
   • Use Stripe's proration_behavior: 'create_prorations' for all changes
5. Implement family dashboard:
   • Sidebar shows family group name and member count
   • Main view: cards for each member with photo, name, threat score, recent alert count
   • Click member → detailed view with their services, alerts, and settings
   • Consolidated family threat score (from correlation engine)
6. Implement per-member service configuration:
   • Primary user assigns which services each member gets
   • Default: all members get DarkWatch + SpamShield + RemoveBrokers
   • HomeTitle and VoicePrint limited by property/voice enrollment slots
   • Members can configure their own watchlist items within assigned services
7. Implement notification routing:
   • Critical alerts notify primary user AND affected member
   • Billing notifications go to primary user only
   • Member can opt into/off specific alert types
8. Add family plan tiers:
   • Family Fortress: 5 adults + unlimited children, $45/mo
   • Family Guard: 3 adults + unlimited children, $35/mo
   • Enforce max member limits at invitation time

tests:

• Unit: Proration calculation for add/remove/upgrade scenarios
• Integration: Full invitation flow from email to account linking
• E2E: Create family plan → invite 2 members → verify billing → remove member → verify prorated credit

acceptance_criteria:

• Primary user can send email invitations to family members
• Invitations expire after 7 days and can be resent
• Members can accept invitations and join family group
• Adding member mid-cycle creates prorated charge on next invoice
• Removing member mid-cycle creates prorated credit on next invoice
• Family dashboard shows all members with threat scores and alert counts
• Primary user can configure which services each member has access to
• Members cannot see other members' sensitive breach details (only score + summary)
• Billing notifications route to primary user; security alerts route to affected member
• Max member limits enforced at invitation (5 for Fortress, 3 for Guard)
• Plan downgrade prevents inviting beyond new tier's member limit
• All family plan changes handled via Stripe proration (no manual calculations)

validation:

• Run vitest run billing.test.ts — extended tests for family proration
• Manual: Send invitation to test email, click link, verify member joins family
• Stripe Dashboard: Verify proration items appear on invoices after member changes
• Dashboard: Family view shows 3 member cards with individual threat scores

notes:

• Family plans have 30–50% lower churn than individual plans — this is a critical retention driver
• Stripe's proration_behavior handles most math automatically — trust it
• Children's accounts should be restricted: no dark web monitoring for minors, only spam/basic alerts
• Consider adding "family safety alerts" — notify primary user if child receives suspicious contact
• The existing invitation.ts schema may need extension for family-specific invitation tokens
• Member removal should not delete their account — just unlink from family group
• Children (under 18) should have simplified dashboard — no breach details, only "safe/attention needed"