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

Family questionnaires let a coach assign structured intake or follow-up forms and let the family complete them over time. Every assignment is a snapshot of the selected coach template, so later template edits do not rewrite the questions or answers already shared with a family.

A family may have several questionnaires. Each has its own progress, answers and submission state. The assigned coach can review the same snapshots but cannot answer them on the family's behalf from the questionnaire screen.

Each questionnaire contains a title, template reference and name when available, coach/practice identity and branding, ordered questions, an answer map, timestamps and one of three statuses:

Questions are grouped by section and ordered by sortOrder. A section can carry explanatory copy; each question can also have help text and a required flag.

Contract limits include 5,000 characters for text answers, 50 selected values in an answer, 30 choices per question and 80 questions per coach template. The server validates answer type, option identifiers and free-text shape against the questionnaire snapshot.

1. The family route requests all questionnaire snapshots visible through the current active coach assignment.
2. The list is newest first and shows each questionnaire's title, status and answered-question progress.
3. Selecting a card opens the full form in a sheet while preserving the collection behind it.
4. The coach route uses the same collection and form presentation with editing controls removed.

1. The form renders sections, descriptions, help text and the correct input for each question type.
2. Changes remain local until Save draft or Submit is used.
3. The client tracks which question identifiers changed and sends only those answer entries.
4. The platform merges that patch into the saved answer map, so untouched answers remain intact.
5. Draft saving permits incomplete required questions. A partially answered form becomes inProgress.
6. A family can reopen the questionnaire and continue from the server-saved values.

1. Submit sends the changed answers with submit: true.
2. The platform checks every required question against the final merged answer set, not only the current patch.
3. Missing required answers return a validation error and the form remains editable.
4. A successful submit sets status to submitted and records submittedAt.
5. Later saves do not roll a submitted questionnaire back to inProgress and do not replace its original submission timestamp.

1. An authorized assigned coach sees the same titles, sections, question labels and stored answers.
2. The coach view is explicitly read-only: it has no draft-save or submit action.
3. Multiple snapshots remain distinct, allowing intake and later follow-up questionnaires to coexist.

Normally a questionnaire snapshot is stable. Compatibility paths can nevertheless replace or reshape a snapshot while a family still has unsaved edits. If the server rejects an answer because it no longer matches the current questions, the mobile app:

1. reloads the questionnaire collection;
2. keeps dirty answers only where the question still exists and the value remains valid;
3. drops an unsaved value for a removed or incompatible question;
4. asks the family to review and retry; and
5. closes the sheet if the questionnaire itself no longer exists.

This recovery protects valid local work, but it cannot safely preserve an answer whose question or answer type has been removed.

1. A family can read and change only snapshots whose familyUserId is its own trusted platform identity.
2. Family artifact visibility is tied to the current active coach relationship; the client cannot supply another family identity to the family routes.
3. Coach reads require the matching active assignment, active organization membership, eligible organization and coach billing state, and a support entitlement that allows record access.
4. The coach questionnaire screen is read-only even though the coach may manage templates and create new snapshots elsewhere.
5. Template changes and removal never mutate historical family snapshots or silently reassign their answers.
6. Questionnaire answers are family profile data. They are not included in public routes or notification previews.

1. The family list supports more than one questionnaire and reports independent progress and status.
2. All six question types render and round-trip values accepted by the shared contract.
3. Draft save merges changed answers without requiring incomplete required fields.
4. Submit fails when a required response is absent and succeeds against the complete merged answer set.
5. Submitted state and the first submission timestamp survive later saves.
6. The assigned coach can review but cannot alter family answers from the questionnaire route.
7. A stale local form recovers still-valid dirty answers after a schema conflict.
8. Ineligible coaches and unrelated families cannot read the snapshot collection.

• mobile-web/src/routes/FamilyQuestionnairesScreen.tsx
• mobile-web/src/components/FamilyQuestionnaireForm.tsx
• mobile-web/src/components/FamilyQuestionnaireSheet.tsx
• 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/packages/shared/src/family-profile-artifacts.ts

• 03 — Coach invitations and family linking
• 18 — Session prep and coach report
• 20 — Questionnaire template management