Skip to main content
Synced from the repo — do not edit here

Canonical source: docs/claude/app-redesign-onboarding-config.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

App Redesign — Configurable Onboarding (clinic templates)

Companion to app-redesign-roadmap.md. Extends the existing white-label plan (project_white_label_app: branding + section toggles + onboarding config + basisflow-web preview). Figma frames: 🚀 Onboarding · States · Variants page (Welcome / Goals / Connect).

Decision (George): Onboarding is not a fixed flow. It's a set of template steps each clinic configures from basisflow-web — enable/disable, reorder, add images, custom copy — with the clinic's branding auto-applied (WhiteLabelConfig). BUT a core set of steps is mandatory for all clinics and cannot be disabled, because they gather auth + the permissions the app needs to function.

Two step classes​

🔒 Mandatory (locked — always shown, cannot be disabled, order fixed within the flow)​

These gather account + the grants the app can't work without:

  • Account / login (auth — sign up / sign in)
  • Legal & consent (HIPAA consent, Terms) — required to handle PHI
  • Connect a device / wearable (the sync step) — the permission gateway for health data
  • Health data permissions (HealthKit / Health Connect grants; notifications permission)

Clinics may restyle these (branding, hero image, copy tweaks) but cannot remove them.

🎨 Configurable (clinic enables/disables/reorders/customizes; branding auto-applied)​

  • Welcome / value-prop (hero image + headline + subcopy)
  • Goals selection (clinic picks which goal options appear)
  • Education / intro screens (0–N custom slides with image + copy)
  • Profile basics (name, DOB, sex, height — can defer to later)
  • Baseline questionnaire (or defer to Plan › Tasks documentRequests)
  • Book intro consult (CTA into scheduling)

Config schema (what basisflow-web writes; app reads)​

Stored per clinic (e.g. clinicsv2/{clinicId}/settings/onboarding — confirm path against existing white-label config):

OnboardingConfig {
  clinicId
  steps: [
    {
      id,                         // stable id
      type: 'welcome' | 'goals' | 'education' | 'profile_basics' |
            'questionnaire' | 'book_consult' | 'custom' |
            'auth' | 'consent' | 'connect_wearable' | 'permissions',
      enabled: bool,              // configurable steps only; locked steps are always true
      locked: bool,               // true for auth/consent/connect_wearable/permissions
      order: int,
      copy: { title, body },      // clinic-editable
      imageUrl,                   // clinic-uploaded hero image (optional)
      options?: [...]             // e.g. goal choices for type=goals
    }
  ]
  branding: <auto from WhiteLabelConfig — logo, interactive.primary, display font>
}
  • The app renders steps by order, skipping enabled:false.
  • locked steps ignore enabled=false (safety) — the basisflow-web UI must disable the toggle for them.
  • Branding is not in this doc — it's inherited from WhiteLabelConfig (the same allowlist the Hatter white-label proof uses: interactive.primary, surface.brand, display font).

basisflow-web editor (deferred UI, but backend must support the schema)​

Per project_white_label_app, the clinic-side editor lives in basisflow-web with a preview. It writes OnboardingConfig. UI not built here; the schema above is the contract. Mandatory steps appear in the editor as locked rows (visible, restyle-only, toggle disabled).

App-side (basishybrid)​

  • Onboarding driver reads OnboardingConfig, renders the ordered enabled steps, applies WhiteLabelConfig branding.
  • Locked steps hard-coded into the driver so a missing/misconfigured config can never skip auth/consent/permissions.
  • Falls back to a default template if no clinic config exists.

Backend to build​

  • OnboardingConfig doc + read path in app, write path in basisflow-web.
  • Enforce locked steps server-side + in the app driver (never skippable).
  • Image upload/storage for per-step hero images (Storage rules for the path).
  • Default template config seeded per new clinic.
  • Branding pulled from WhiteLabelConfig (already in white-label scope).

Open decisions​

  • Exact config doc path (align with existing white-label config location).
  • Whether "consent" and "notifications permission" are hard-locked or clinic-optional.
  • Whether baseline questionnaire lives in onboarding vs Plan › Tasks (documentRequests) — likely Tasks, to reuse that pipeline.