Onboarding

The onboarding system guides new schools through registration, configuration, and business setup. Mirror pattern, ~166 files, 16 active steps in 3 groups, driven by WizardLayout. Typical completion: 10–30 minutes.

Steps

Group 1 — Basic information

Group 2 — School setup

The schedule step is defined in OnboardingStep with its own component directory but is not in active navigation. Lives at order: 5.5 in config.ts for future activation.

Group 3 — Business and legal

After all steps the user lands on /congratulations for a smart redirect (school subdomain dashboard or main domain depending on session state).

Active step order is ONBOARDING_CONFIG in src/components/form/footer.tsx. Authoritative metadata (labels, validation, group, order) is ONBOARDING_STEPS in src/components/onboarding/config.ts.

Auth handshake

Four-stage flow:

1. Start — Unauthenticated user visits /get-started or /onboarding. start-onboarding action persists intent in a cookie and redirects to /login.
2. Authenticate — Standard login. Callback URL routes back to /onboarding.
3. Provision — initializeSchoolSetup() calls ensureUserSchool() (src/lib/school-access.ts) — atomic db.$transaction creates the School row, SchoolMember (binds user as ADMIN), seeds default YearLevels. Idempotent.
4. Refresh + redirect — _sessionRefreshRequired: true triggers client refetch of /api/auth/session; _redirect sends to next step.

Ownership enforced by requireSchoolOwnership(id) on every step's load. Cross-tenant access raises TenantError.

Multi-tenant integration

• Subdomain routing — /onboarding and children live on a main domain (ed.databayt.org or balqalam.com), not on a subdomain. Subdomain assignment happens at the Subdomain step, and the suffix shown there follows the root the visitor actually arrived on (rootDomainFromLocation()), so a school signing up via balqalam.com is quoted a balqalam.com URL.
• Locale in step URLs — every onboarding URL must carry its [lang] segment. A bare /onboarding/... path is treated as locale-less by proxy.ts, which then re-derives the locale from the NEXT_LOCALE cookie or Accept-Language header rather than the page the user was on — flipping Arabic users to English mid-wizard. FormFooter navigates correctly on its own; steps overriding onNext should save only, or prefix params.lang themselves.
• Database scoping — every read uses requireSchoolOwnership(id) first, then queries scoped by schoolId.
• Session schoolId — JWT carries schoolId after step 1; subsequent steps trust it after re-verification.

Validation

Each step has a Zod schema co-located with its component. Schemas use the i18n factory pattern — same schema produces Arabic or English error messages depending on the dictionary slice.

Copyimport { createTitleSchema } from "@/components/onboarding/title/validation"
 
const schema = createTitleSchema(dictionary)
const result = schema.safeParse(input)

Root validation.ts exports validateStep(step, data, dictionary) and getRequiredFieldsForStep(step) for shared step-aware validation.

Auto-provisioning

When completeOnboarding() runs at the legal step, the school is marked active and a 5-step provisioning chain creates academic infrastructure. Each step is wrapped in try/catch so one failure doesn't block the rest.

Source: src/components/onboarding/legal/actions.ts → src/components/catalog/setup.ts.

setupCatalogForSchool resolves curriculum via inferCurriculum():

API routes

Server actions

In src/components/onboarding/actions.ts:

Key files

Troubleshooting

See also

• Multi-tenancy — auth handshake, tenant context
• Pattern — mirror pattern, file conventions
• Authentication — login flow