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

Documentation status: complete for the current implementation

Reviewed: 2026-07-21

Rollout status: implemented but explicitly gated

Primary users: a linked family and its genuine assigned coach; owner moderation is operational

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

Coach–family messaging provides one private conversation for each coach assignment. It supports inbox previews, unread state, paginated history, idempotent sending, participant pause/push preferences, reporting, owner moderation, relationship-aware history and automatic retention.

The feature is implemented in all three application layers, but repository code alone does not prove that it is enabled in a deployed environment. Server capability, organization canary, beta UI and client-build gates must all agree before a person sees or uses chat.

Chat is available only when every applicable layer permits it:

GET /auth/me supplies role-specific family, coach and owner capability values. A disabled role includes feature_off, not_in_canary or role_unavailable. Push capability separately reports whether the server enables it and the minimum wrapper version.

The application must treat server capability as authoritative. A visible client control does not bypass a disabled server capability, relationship state or moderation state.

1. There is one conversation per family assignment, not one global thread per pair of users.
2. Conversation lifecycle is active, former or purged.
3. Moderation is open or disabled.
4. The participant-facing effective state is active, participant_disabled, relationship_unavailable, owner_disabled or former.
5. Each participant owns chatEnabled, pushEnabled and a last-read sequence independently.
6. Messages receive a monotonically increasing sequence in the conversation.
7. A message body is trimmed, non-empty and limited to 4,000 Unicode code points.
8. clientMessageId is a UUID idempotency key. Retrying the same send returns the existing message rather than creating a duplicate.

1. The inbox returns the other participant's display name, last-message preview/time, unread count, lifecycle/effective state, personal settings and any history-expiry date.
2. Conversation pages default to 30 and permit up to 100 records with an opaque cursor.
3. The coach portal supports local search over its loaded conversation presentation and paginated retrieval.
4. A separate unread endpoint allows the navigation badge to update without loading every thread.
5. Conversation resource changes trigger an opaque realtime invalidation and refetch. Mobile also uses a periodic safety refresh while appropriate.

1. A thread requests the newest 50 messages by default and can request up to 100.
2. Older pages use beforeSequence, avoiding timestamp ambiguity.
3. Read state advances through an explicit throughMessageId. It does not infer that every delivered push was read.
4. Current participants see the composer only when effectiveState is active.
5. Former/read-only states retain clear copy explaining why sending is unavailable and, for the family, when history expires.

1. The client creates a UUID, adds a pending message and sends the trimmed body.
2. A successful first creation returns HTTP 201. An idempotent replay returns HTTP 200 with the same durable message.
3. A failed optimistic message remains identifiable and can be retried using the same UUID.
4. The platform serializes conversation sequence allocation and rechecks access inside the write path.
5. Server limits are 20 messages per sender per minute and 300 messages per conversation per hour.

1. Either participant can disable their own chat participation without deleting the conversation.
2. New messages require a current eligible relationship, open owner moderation and both participants enabled.
3. Personal push can be changed independently, but delivery also requires effective active chat and server/client/native push eligibility.
4. Disabling chat alone does not convert the relationship to former and does not start the six-month former-history clock.

1. Either participant can report the conversation or a specific message.
2. Categories are harassment, privacy and other; optional detail is limited to 1,000 Unicode code points.
3. clientReportId makes retries idempotent. A reporter is limited to 10 reports per day.
4. Reports move through open, reviewing and resolved in owner tooling.
5. An owner can disable a conversation with a moderation reason or reopen it. owner_disabled prevents participant sends while preserving the evidence/history needed for review.

1. Push content is deliberately non-sensitive: New message and Open Littles Baby Tracker to read it.
2. The payload routes back to chat but does not contain sender name or message body.
3. Delivery is rechecked at dispatch for current access, personal chat/push settings, moderation and a compatible registered device.
4. Offline or failed push does not change the durable message or unread state; opening the app reloads from the API.

A relationship becomes former when the assignment is revoked/transferred or support actually ends. Pausing personal chat is not the same event. If the same assignment becomes eligible again before purge, reconciliation may make it available again; after purge, deleted message content is not recoverable. Account deletion can require earlier purge.

The deadline uses a database interval of six calendar months in UTC, not a fixed 180-day duration. The former coach does not retain participant-history access during that window; family and authorized owner workflows are the intended retained readers.

Participant routes exist under the actor-specific prefix: /families/me/chat for family and /coach/chat for coach.

Owner-only routes add conversation/report filtering, detail inspection, moderation and retention operations. They are not available through coach or family sessions.

1. Family and coach routes derive the participant from the trusted session and verify membership in the conversation.
2. Coach access requires a genuine coach session. Synthetic owner view-as and mobile coach view-as contexts do not become chat participants and cannot send.
3. Active sending requires assignment, organization, membership, billing and support eligibility in addition to both participant settings and moderation.
4. A former coach loses access immediately even though family history remains temporarily available.
5. Inbox preview and generic push are intentionally bounded; push never exposes message text or family/coach identity on the lock screen.
6. Reports and owner inspection are privileged operational data and are auditable.
7. Purge removes conversation content rather than merely hiding it from participant clients.

1. Chat remains absent/denied unless server capability and the applicable client gate are enabled.
2. One assignment resolves to one conversation and participant access cannot cross assignments.
3. Inbox unread totals, paginated history and explicit read cursors remain consistent after realtime refetch.
4. Retrying a send with the same clientMessageId never creates a duplicate.
5. Sending is permitted only in active effective state and rate limits are enforced server-side.
6. Participants can pause themselves and manage push without deleting history.
7. Report creation is idempotent, category/detail validated and owner moderation can disable sending.
8. Former family history displays its deadline; the former coach is denied and no participant can send.
9. The retention worker purges expired former conversations, and push payloads remain generic.

• mobile-web/src/features/coach-family-chat/
• mobile-web/src/App.tsx
• mobile-web/src/feature-flags.ts

• admin-web/src/features/coach-family-chat/
• admin-web/src/feature-flags.ts

• platform/apps/api/src/routes/coach-family-chat-routes.ts
• platform/apps/api/src/routes/family-chat-routes.ts
• platform/apps/api/src/routes/coach-family-chat-route-helpers.ts
• platform/apps/api/src/services/coach-family-chat-service.ts
• platform/apps/api/src/services/coach-family-chat-retention-service.ts
• platform/apps/api/src/services/coach-family-chat-push-service.ts
• platform/apps/api/src/feature-flags.ts
• platform/packages/shared/src/coach-family-chat.ts
• platform/docs/multi-tenancy/coach-family-chat/

• 16 — Family caseload and support lifecycle
• 22 — Family activity notifications
• 32 — Realtime updates and push notifications