Synced from the repo — do not edit here

Canonical source: docs/claude/onboarding.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.

Onboarding

Client onboarding flows for account setup, health data connection, and clinic intake.

Onboarding Types

Type	Platform	Description
Client App Onboarding	Basis Hybrid	Health permissions, profile setup
Clinic Intake Forms	Web Forms	Custom forms, consents, health history
Lead Conversion	Growth Module	Lead -> Client conversion

Client App Onboarding (Basis Hybrid)

File: basishybrid/lib/view/routes/route_onboarding.dart

Pages (in order):

1. OnboardingDataPrivacy - Privacy policy acceptance
2. OnboardingHealth - Health data permissions (Apple Health/Google Fit)
3. OnboardingAnalyze - Analytics opt-in
4. OnboardingDevices - Connect wearable devices
5. OnboardingUserInfo - Profile info (name, DOB)
6. OnboardingSleeptimesFetcher - Sleep schedule
7. OnboardingWindowClock - Daily schedule
8. OnboardingNotifications - Notification permissions
9. OnboardingCalendar - Calendar integration (iOS/Android)

Completion:

• Sets user.onboardingVersion to current version
• Enables background health sync
• Triggers initial chat greeting

Clinic Intake Forms

File: functions_onboarding.py

Custom intake forms configured per clinic:

• Stored in clinicsv2/{clinic}/settings/onboarding
• Rendered via hosted forms page (forms.basishealth.io)
• Token-based secure access

Configuration:

interface OnboardingFormConfig {
  key: string;            // Unique form identifier
  title: string;          // Display title
  enabled: boolean;
  required: boolean;
  fields: FormField[];    // Form schema
}

State Storage:

clinicsv2/{clinic}/clinic_users/{uid}/onboarding
  - nonce: string         // Security token
  - allCompleted: boolean
  - welcomeSent: boolean
  - forms: {
      [formKey]: {
        title: string
        required: boolean
        completed: boolean
        completedAt: timestamp
      }
    }

Client Invitation Flow

Staff App -> clinic_service: add_clinic_user (email, name)
  -> Firestore: Create clinic_user record
  -> Initialize onboarding state
  -> Mailersend: Send invite email
  -> Client clicks link, creates account
  -> Complete profile
  -> Download app, connect health

Key Files

File	Purpose
functions_onboarding.py	Form configuration and submission
functions_clinic.py -> add_clinic_user	Client invitation
basishybrid/.../route_onboarding.dart	Mobile onboarding UI
basishybrid/.../route_intro.dart	Login/signup flow