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

Documentation status: complete for the current implementation

Reviewed: 2026-07-21

Primary users: coaches and invited family members

Surfaces: mobile web app, coach admin portal and platform API

This feature establishes an explicit, consented support relationship between one family and one coach. Coaches can create a one-use email invitation or share code, optionally snapshot a questionnaire and expiry date, and monitor its status. Families can preview the named coach and practice before authentication, accept or decline a pending invitation, or redeem a code.

Acceptance creates the trusted assignment and coach-sponsored premium access. It does not merely set a client-side flag.

The coach chooses one method:

• Email: a valid family email is required and normalized to lowercase.
• Share code: the coach may supply a code, which the UI uppercases, or leave it blank for generation.

The coach can also set an optional expiry date and questionnaire behavior:

• select an active named template;
• use the current default when no explicit selection is available; or
• choose Send later / no questionnaire yet.

For a one-use invitation, the chosen template identity, name, title and questions are snapshotted with the invitation. Later template edits or default changes cannot alter what that family receives. Acceptance creates that questionnaire once; retries do not create duplicates.

1. Summary controls show Pending, Accepted, Expiring and Codes counts.
2. Search matches email, code, family and invitation ID.
3. Status filters include all, pending, accepted, declined, revoked, expired, expiring soon and share codes.
4. “Expiring soon” means a pending invitation with an expiry in the next seven days.
5. A pending invitation can be revoked. Accepted, declined, revoked and expired records remain historical and are not presented as reusable pending invitations.

Coach invitation creation is subscription-gated. A coach without eligible billing is directed to start or resume the coach subscription before creating invitations or managing linked families.

The public preview endpoint normalizes and validates the code and returns only the information needed for informed consent:

1. coach name;
2. practice/organization name and public branding;
3. whether the coach can view logs;
4. whether the coach can edit logs;
5. invitation expiry, when present; and
6. confirmation that consent is required.

Preview does not link the family and does not reveal another family's data.

If no session is present, the screen offers Login and Create family account with the full internal invite route in the safe next parameter. After authentication the family returns to the preview. A non-family actor is denied rather than being linked accidentally.

The consent checkbox must be selected before Redeem invite, Confirm and redeem or Accept becomes available. The request carries literal consentToCoachAccess: true; omitting it is invalid.

The platform then atomically creates or updates the assignment, coach-sponsored entitlement, redemption/invitation state, audit event and any invitation questionnaire snapshot. A welcome modal shows the connected coach/practice after success.

When a family already has an active direct App Store or Google Play subscription, acceptance pauses for an explicit warning. The family can:

• open the relevant store-management page first;
• cancel and keep the invitation pending; or
• acknowledge the active subscription and continue.

The second acceptance includes acknowledgeActiveStoreSubscription: true. The platform rechecks the conflict; acknowledgement is recorded for audit/analytics. A coach relationship does not silently cancel a store subscription.

1. Declining changes only the pending invitation; it does not create an assignment or entitlement.
2. A connected family can use Disconnect coach. Confirmation immediately revokes coach access and removes the named relationship from normal coach tools.
3. Reconnecting a revoked family requires a new invitation or code and fresh family acceptance; a revoked assignment is never silently restored.
4. After disconnect/revocation, ordinary organizations give the family a seven-day premium grace period. The family keeps its account and logs and can continue tracking throughout.

Only one active coach assignment is allowed for a family. Attempts to create a conflicting active relationship are rejected by the platform rather than replacing the current coach in the client.

1. Preview is intentionally public but contains no family identity, logs or tenant-private data.
2. Redemption and acceptance require a family role and explicit consent on the server.
3. A coach can list/revoke only invitations scoped to their authorized practice membership.
4. Assignment and entitlement creation is transaction-backed; client navigation cannot create coach access.
5. Expiry blocks new redemption and constrains coach-sponsored access derived from the invitation.
6. Coach access to logs remains subject to assignment, support and per-operation permissions after acceptance.
7. Family-authored data remains owned by the family after decline, expiry, disconnect or revocation.

1. A coach can create an email invitation and a generated/custom share code with an optional expiry.
2. The selected questionnaire snapshot remains stable if the source template later changes.
3. A signed-out family can preview identity, authenticate and return to the same invitation.
4. No invitation can be accepted before the family consents.
5. Pending email invitations can be accepted or declined from Home and the access screen.
6. Active store billing triggers an explicit warning and acknowledgement, never silent cancellation.
7. A second active coach is rejected and a revoked relationship requires a new invitation.
8. Family disconnect removes coach access immediately while preserving the family account/logs and grace period.

• mobile-web/src/routes/InviteScreen.tsx
• mobile-web/src/routes/FamilyAccessScreen.tsx
• mobile-web/src/routes/FamilyDashboard.tsx
• mobile-web/src/components/CoachAccessConsentCheckbox.tsx
• mobile-web/src/components/CoachInviteStoreSubscriptionConflictDialog.tsx

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

• platform/apps/api/src/routes/invite-routes.ts
• platform/apps/api/src/routes/family-routes.ts
• platform/apps/api/src/routes/coach-routes.ts
• platform/packages/shared/src/invites.ts
• platform/packages/shared/src/family-invitations.ts
• platform/docs/multi-tenancy/05-development-plan.md

• 01 — Account access, onboarding and sign-in
• 04 — Subscriptions, billing and premium access
• 12 — Family questionnaires
• 16 — Family caseload and support lifecycle
• 26 — Organization branding and personalisation