Technical reference. For task-based help, see the corresponding user guide.

Documentation status: complete for the current implementation

Reviewed: 2026-07-21

Primary users: subscribed coaches

Surfaces: coach admin portal, mobile coach workspace and platform API

The family caseload is the coach's operational source of truth for current client relationships. It combines accepted assignments, pending invitations, support dates/status, team labels, recent and unseen activity, baby context and gated entry points such as session prep, family view-as and chat.

The lifecycle intentionally distinguishes expired support from revoked assignment. Expired support can be extended while the assignment remains current. Revocation permanently ends that assignment and requires a new invitation and family acceptance to work together again.

Each family item can contain name/email/profile/timezone, baby count/names, team label, assignment and redemption dates, support dates/status, premium state, edit/date permissions, last/recent activity, unseen summaries and a lightweight sleep summary.

The coach portal pages 10 families at a time. Search covers family name, email, family identifier, baby names and team label. Filters include Active, Paused, Not started and Ended compatibility states; Expired has its own action modal. Quick summary filters also identify:

1. Review: no last activity, or paused/expired/not-started/ended state;
2. Recent: last activity within the previous seven days; and
3. Expired: active assignments whose support entitlement no longer permits record access.

Mobile adds name/status/start/end/baby sorting, period summary, recent activity presentation, today's sleep, running sleep timer and notification mute controls.

1. The platform returns at most one canonical assignment for a family to this coach.
2. A current active assignment with usable support ranks ahead of an expired active assignment, which ranks ahead of a revoked historical assignment.
3. The coach must still be an active organization member and the organization/billing context must allow coach access.
4. Pending, unexpired invitations are returned separately from accepted families.
5. The route accepts scope=current|past|all (and a legacy includePast) for compatibility. The current implementation deliberately returns the visible current/expired active roster; past returns no families and all does not restore revoked records.

“Families worked with all time” is an anonymized analytics count, not a past-family directory. Former names and records cannot be recovered by changing the roster query scope.

Premium family access and coach record access are related but not identical. The roster presents both support status and the resolved premium disabled reason so the coach can distinguish expiry, billing and assignment problems.

1. The coach can set or clear startsAt and endsAt where canManageSupportDates is true.
2. If both exist, the end cannot precede the start.
3. An already expired entitlement can be reactivated only by supplying an end date later than now.
4. Portal date inputs send the start at 00:00:00.000Z and end at 23:59:59.000Z for the selected UTC calendar day.
5. Changes are audited and chat/access capability is reconciled after a support-boundary change.

1. Pausing requires an end date and is rejected for already expired support.
2. Paused support remains visible and continues to allow authorized coach record access.
3. Resuming a pause extends the existing end by the elapsed paused duration, preserving the intended amount of active support time.
4. An expired paused/active record must first be extended with a future end date.

1. Expired families are removed from the ordinary current cards and shown in a dedicated modal/control.
2. The coach chooses a future end date to extend support, or confirms revocation.
3. Until extension succeeds, protected record fields, session prep, private notes, notifications and messaging are unavailable through backend authorization.

1. The UI explains that removal is not a reversible pause and asks for confirmation.
2. Revocation changes the assignment to revoked, expires related coach-invite entitlements, updates organization capacity and writes audit events.
3. Chat relationship reconciliation runs so the conversation enters its former lifecycle.
4. The family disappears from the coach's current workspace.
5. The family can also revoke its own active coach assignment from its access controls.

Some client types and portal UI still contain a Restore coach access action for an ended row. The platform route PATCH /coach/families/:familyId/restore is intentionally retained only as a compatibility endpoint and always returns 403 with guidance to send a new invite.

Do not build a recovery workflow around the restore response type. A revoked assignment must not be mutated back to active; the family must knowingly accept a new invitation.

1. A current family can be assigned one label from the organization's saved label list or cleared to Unassigned.
2. Labels are normalized for whitespace and case-insensitive uniqueness.
3. A label is limited to 40 characters; an organization can save up to 25.
4. Organization-level rename operations can update affected family selections. Label-list management belongs to Feature 23.

1. Roster unseen counts use an assignment lastActivitySeenAt cursor, falling back to redemption/assignment time.
2. Opening a family view-as can call PATCH /coach/families/:familyId/activity-seen and clear the general roster unseen summary.
3. This cursor is separate from the per-family notification-feed watermark in Feature 22. Clearing one must not be assumed to clear the other.

1. Every operation requires a coach role, matching assignment ownership, active organization membership and an eligible organization/subscription.
2. Record reads also require canViewLogs and a support entitlement that allows record access; writes require the corresponding trusted permission.
3. Paused support remains record-accessible by design. Expired, revoked, canceled and inactive-billing support does not.
4. Expired families may remain minimally visible so the coach can extend or revoke them, but activity, sleep and unseen detail is withheld.
5. Revoked assignments do not appear through past/all roster scopes. Historical counts remain aggregate-only.
6. Team labels are organization-scoped operational metadata, not a global cross-tenant directory.
7. Client status filters and disabled buttons are presentation only; backend checks run on every mutation.

1. Search, status/team filters, sorting and portal pagination operate on the authorized current list.
2. Active, paused, not-started, expired and revoked meanings are not conflated.
3. Pause requires a valid end date; resume extends the end by elapsed pause time.
4. Expired support can be extended only with a future end and exposes no protected record detail before success.
5. Revocation removes current access and cannot be reversed through the restore compatibility route.
6. Team labels must come from the saved organization list and respect count/length limits.
7. General activity-seen and activity-notification-seen remain separate cursors.
8. scope=past and scope=all cannot enumerate former families.

• admin-web/src/routes/FamiliesPanel.tsx
• admin-web/src/routes/FamilyInvitationsPanel.tsx

• mobile-web/src/routes/CoachDashboard.tsx
• mobile-web/src/components/CoachFamilyPicker.tsx
• mobile-web/src/components/CoachExpiredFamiliesModal.tsx

• platform/apps/api/src/routes/coach-routes.ts
• platform/apps/api/src/services/prisma-invite-flow-service.ts
• platform/apps/api/src/services/coach-support-window-service.ts
• platform/apps/api/src/services/authorization-service.ts
• platform/packages/shared/src/coach.ts
• platform/packages/shared/src/family.ts

• 03 — Coach invitations and family linking
• 14 — Coach–family messaging
• 17 — View as family
• 18 — Session prep and coach report
• 22 — Family activity notifications
• 23 — Practice settings and team labels