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

Documentation status: complete for the current implementation

Reviewed: 2026-07-21

Primary users: linked family members and their assigned coach

Surfaces: mobile web app and platform API

Published sleep plans present the coach's current guidance to a family in a branded, mobile-friendly format. A plan can combine ordered sections, paragraphs, bullet points, images and an optional PDF attachment. Draft and archived versions stay in the coach authoring workflow and are never returned by the family-facing list.

A family-visible plan carries coach and organization identity, practice branding, title, version, publication timestamps, ordered sections, and optional PDF metadata.

Each plan has 1–30 sections. A section has a title and up to 80 ordered blocks:

The plan title and each section title are limited to 180 characters. Image alt text and captions are limited to 500 characters. The family renderer preserves the coach-defined section and block order.

1. The family route asks the platform for the current relationship's sleep plans.
2. The platform returns only records whose status is published.
3. The coach read route applies the same published-only filter, so coach view-as matches the family experience rather than exposing drafts.
4. Cards display the organization/coach attribution, branded colours and plan title before rendering the ordered content.
5. The contract supports a collection. Normal authoring maintains one current non-archived plan, but the family screen safely renders every published record returned by the API.

1. Paragraphs and bullets are rendered as readable structured copy, not as raw editor markup.
2. An image block requests a signed download URL from the sleep-plan-images bucket with a 900-second lifetime.
3. Alternative text falls back in this order: explicit alt text, caption, file name.
4. A loading placeholder is shown while the URL is being signed and the image is loading.
5. If signing or image loading fails, the screen shows an image-unavailable state without hiding the rest of the plan.

1. If pdfAssetId and file metadata are present, the plan displays an attachment action.
2. Tapping it requests a fresh 900-second signed URL from sleep-plan-pdfs.
3. The WebView asks the native wrapper or host browser to open that URL externally.
4. If the URL cannot be signed or the host declines to open it, the user sees Could not open the sleep plan PDF and can retry.

Signed URLs are intentionally temporary. Reopening an image screen or tapping the PDF again requests a fresh URL; the durable plan stores only the private asset identifier and metadata.

1. A coach draft is invisible to the family.
2. Publishing makes the saved plan available on the next load or realtime refresh path.
3. Saving a previously published current plan as draft removes it from the family-facing published list until it is published again.
4. Archiving removes that current plan from family visibility and creates a new coach draft.
5. Restoring history creates/replaces a coach draft; it does not silently republish the archived content.

1. Family routes derive the family identity from the authenticated session; a family cannot request another family's plan collection.
2. Only published plans cross the family-facing boundary. Draft and archived records remain coach-only.
3. Coach reads require the matching active assignment, active organization membership, eligible organization and billing, and support record access.
4. Private files remain in dedicated Supabase Storage buckets. The API authorizes the request before issuing a time-limited download URL.
5. A signed URL is a temporary bearer link and must not be copied into durable page content, logs or analytics.
6. Practice branding shown on the card comes from trusted organization metadata stored with/resolved for the artifact.

1. Family and coach view-as routes render only published plans.
2. Section and paragraph/bullet/image order matches the stored plan.
3. Image signing uses the correct private bucket and a short expiry, with useful alt-text fallback.
4. A signed PDF opens through the host bridge and reports failure without losing the page.
5. Empty, API-error, image-error and PDF-error states are recoverable.
6. Saving as draft, archiving or restoring history never exposes un-published edits to the family.
7. An unrelated or ineligible coach cannot request plan content or signed file URLs.

• mobile-web/src/routes/FamilySleepPlansScreen.tsx
• mobile-web/src/webview/native-messages.ts
• mobile-web/src/api/client.ts

• platform/apps/api/src/routes/family-routes.ts
• platform/apps/api/src/routes/coach-routes.ts
• platform/apps/api/src/services/family-profile-artifact-service.ts
• platform/apps/api/src/services/prisma-file-url-service.ts
• platform/packages/shared/src/family-profile-artifacts.ts

• 03 — Coach invitations and family linking
• 21 — Sleep-plan authoring and history
• 26 — Organization branding and personalisation
• 30 — Signed files and profile media