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 and platform API

Questionnaire templates let a coach maintain a reusable catalogue of intake and follow-up forms. A template defines the family-facing title, explanatory copy, sections, question order and response controls. One active template is the default, but a coach can choose any active template when inviting a family or adding a later questionnaire in Session Prep.

Templates are authoring sources, not live family forms. Assigning one creates a self-contained snapshot. Editing, changing the default or removing the source template does not rewrite an existing family's questions or answers.

The portal protects the questionnaire manager with the coach subscription gate. The platform also verifies the coach role, active organization membership, organization state and coach subscription instead of trusting route visibility.

The active list is sorted with the default first, then by name and creation time. Each card shows its internal name, family-facing title, question count, update date, default badge and unsaved badge. The API also returns the assigned-family-questionnaire count; the current manager uses that count in the removal confirmation rather than displaying it on every card.

1. A coach/organization scope always has an active default. Reading an empty catalogue creates the built-in starter template.
2. The first explicitly created template is default only if no active template already exists.
3. Set as default moves the default marker; it does not assign or alter any family questionnaire.
4. New invitations preselect the current default, while compatible clients that omit a questionnaire choice also fall back to the server's active default.
5. Reusable invite codes resolve the current default when each family redeems the code. A one-use invitation instead stores its selected/default template snapshot when the invitation is created.

Every template has:

1. an internal questionnaire name used to distinguish templates in coach tools;
2. a family-facing title;
3. optional descriptive copy; and
4. 1–80 ordered questions.

The editor keeps changes in browser memory until Save. Switching to another template within the mounted manager preserves each template's local dirty draft and displays an Unsaved badge. Reloading or leaving the page does not have a dedicated unsaved-change guard, so uncommitted edits can still be lost.

Each question requires a section and question label. Questions with the same normalized section name are presented together. A section description is edited on the first question in that section and normalized onto every question in the group when saved.

1. Add question appends a long-text starter question.
2. Up/down controls reorder questions and the persisted sortOrder is rebuilt from the visible order.
3. A question can be removed only while at least one question remains.
4. Every question can be required or optional and can include family-facing help text.

Single- and multi-choice questions require at least one non-empty option and support up to 30 options. Each option has a stable identifier, a display label and an Ask for details switch. Typing Other as an option label automatically turns that switch on, but the coach can turn it off again. When enabled, a family selecting the option can add its own text.

New question/option identifiers are generated by the editor. Option identifiers derived from labels are made unique before write; the server trims option IDs and rejects duplicate question or option IDs. Both kinds are limited to 80 characters by the shared contract. Family answers are validated later against the identifiers and types frozen into their assigned snapshot.

1. New creates a template with the internal name New questionnaire, title Pre-session sleep questionnaire, one Session prep long-text question and starter description.
2. The server returns the durable template and the editor selects it immediately.
3. The new template does not become default when another active default already exists.

1. Name, title, description, section content, question text, type, required state, help text and options remain local until Save.
2. The client validates the whole template, displays a summary and scrolls to the first invalid field.
3. A successful patch replaces the local copy with the normalized server response and clears its dirty badge.
4. A failed save leaves the local edits available for correction or retry.

Template writes do not carry a revision or expectedUpdatedAt. Two tabs editing the same template therefore use last-write-wins behavior; saving an older tab can replace a newer saved version.

Duplicate creates a new active template using the selected template's current in-memory content and adds “copy” to its name. This means unsaved edits in the selected template are included in the copy even though the source itself has not been saved. The duplicate has a new identity and is not default.

Set as default updates the active collection so exactly the selected template is default. It affects subsequent default selection only; issued one-use invitation snapshots and assigned family questionnaires remain unchanged.

“Remove” is a soft archive of the template:

1. the final active template cannot be removed;
2. removing the default selects another active template as the replacement before archiving it;
3. the archived template disappears from the manager and from new selection lists;
4. the response reports how many family questionnaires were retained; and
5. no family snapshot is reassigned, rewritten or deleted (reassignedFamilyQuestionnaireCount remains 0).

The portal confirms removal, explicitly warns when families use the template and notes that removal cannot be undone from that screen. Current list/update routes address active templates only, so there is no user-facing restore path for an archived template.

The current Session Prep flow sends { templateId } to the plural create endpoint. Each use appends a new independent snapshot, even if the family already has questionnaires. Existing questions, answers, status and submission timestamps are never overwritten.

Older released clients still have singular endpoints:

1. singular read may lazily create a default questionnaire when none exists, unless an accepted invitation explicitly chose send-later;
2. singular template selection and singular write operate on the latest snapshot; and
3. replacing that latest snapshot keeps only answers whose question identifiers remain valid, recalculates progress and clears submission state.

Current coach tooling uses the plural collection/create path. New work must not use a compatibility mutation when the intended outcome is “add another questionnaire.”

1. Templates are scoped by both coach user and organization; a coach cannot address another coach's template ID.
2. Template management requires a coach role, active organization membership, an active/trialing organization and qualifying coach subscription.
3. Creating a family snapshot additionally requires the matching active assignment and record access for that family.
4. Only active, non-archived templates can be selected for a new family snapshot.
5. Stored invitation and family snapshots remain readable independently of later source-template edits or removal.
6. Family users never receive the coach's full template catalogue; they receive only questionnaires assigned to them.

1. A coach can create, edit, duplicate and select among multiple named templates.
2. Exactly one active template is default for each coach/organization scope.
3. All six question types round-trip with sections, help text, required state and stable ordering.
4. Choice questions cannot save without a valid option; Other can request free text.
5. Dirty state is visible and server failures do not discard the editor draft.
6. Removing the final template is denied and removing a used template retains every family response exactly.
7. One-use invitations preserve the exact selection made at invitation time.
8. Send later creates no questionnaire on acceptance.
9. Session Prep appends a new snapshot and never overwrites earlier answers.
10. Compatibility singular mutations are not mistaken for the current plural add flow.

• admin-web/src/routes/QuestionnaireTemplatePanel.tsx
• admin-web/src/routes/FamilyInvitationsPanel.tsx
• admin-web/src/routes/SessionPrepArtifactsPanel.tsx
• admin-web/src/routes/AdminDashboard.tsx
• admin-web/src/api/client.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-invite-flow-service.ts
• platform/packages/shared/src/family-profile-artifacts.ts
• platform/docs/multi-tenancy/05-development-plan.md

• 03 — Coach invitations and family linking
• 12 — Family questionnaires
• 18 — Session prep and coach report