Onboarding — Code Map
Web (the wizard lives entirely in the web app)
Routes
| File | Description |
|---|---|
apps/web/src/app/[lang]/(protected)/onboarding/page.tsx | Server component. Calls getCurrentUserServer. If memberships.length > 0 → redirect to /{lang} (member) or /{lang}/dashboard/overview (staff). Otherwise renders <OnboardingContent />. |
apps/web/src/app/[lang]/(protected)/onboarding/onboarding-content.tsx | Client component. Wraps OnboardingProvider (OnboardJS) with setupWizardSteps, PostHogPlugin, localStorage persistence. Holds handleFinish (the API call chain). |
apps/web/src/app/[lang]/(protected)/onboarding/loading.tsx | Loading state. |
Step components
apps/web/src/components/onboarding/steps/
| File | Step id | Reads/writes |
|---|---|---|
org-step.tsx | org | Reads flowData.orgName/orgType; writes via updateContext. Uses OrgTypeSelector. |
legal-step.tsx | legal | Embeds LegalAcceptanceForm (legal module). Sets legalConsentsAccepted=true on accept. |
done-step.tsx | done | Read-only summary using flowData.orgName. |
Shared UI under apps/web/src/components/onboarding/
| File | Purpose |
|---|---|
setup-wizard-ui.tsx | Renders progress bar, step shell, navigation buttons. Uses useOnboarding(). |
org-type-selector.tsx | Three-tile selector (physical/online/hybrid). |
option-tile.tsx | Reusable selectable card. |
address-autocomplete.tsx | Google Places autocomplete; not currently wired into the 3-step wizard but reused in settings. |
class-type-form.tsx | Class type form; reused in dashboard schedule settings. |
day-selector.tsx, delivery-mode-selector.tsx | Reused in program creation flows. |
invite-members-form.tsx (+ driver + int.spec) | Email-list invite UI; used post-onboarding from settings/members. |
Providers
| File | Purpose |
|---|---|
apps/web/src/providers/onboarding-provider.tsx | Exports createPostHogPlugin<T>() — wraps @onboardjs/plugin-posthog with FitKit globals (onboarding_variant). |
apps/web/src/config/onboarding-steps.ts | Exports SetupWizardContext type + SETUP_WIZARD_INITIAL_CONTEXT. |
Guided tour (FIT-93 Phase B)
| File | Purpose |
|---|---|
apps/web/src/components/guided-tour/ | Tour overlay, tooltip, spotlight components (TODO: confirm full file list). |
users.guided_tour_completed_at | Persists tour completion across sessions. Set via PATCH /users/me. |
API
The wizard hits these endpoints in order:
| Method | Path | Module |
|---|---|---|
| POST | /organizations | organizations |
| POST | /legal/consents | legal (out of bucket) |
| POST | /organizations/:id/onboarding-complete | organizations |
| GET | /users/me | users-auth |
Server-side guard uses getCurrentUserServer(lang) from apps/web/src/lib/api.ts.
Tests
| File | What it covers |
|---|---|
apps/web/src/components/onboarding/invite-members-form.int.spec.tsx | Invitations form (used post-onboarding). |
apps/web/e2e/specs/onboarding*.spec.ts (TODO: verify by ls) | End-to-end wizard run. |