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.

Location picker

One component, src/components/atom/mapbox-location-picker.tsx, sets every address in the app. That includes this step, school settings, the student and teacher add wizards, the public application, and transportation stops. It replaces separate country, city and district fields with a single search field, the user's current location, and a map.

• Search uses Mapbox Geocoding v6, scoped to the school's country and ranked around the school. Typing "الرياض" from a Khartoum school finds the Khartoum neighborhood, not Saudi Arabia. If the school's country has no match, the search retries worldwide. Results go down to blocks such as "كافوري مربع 9". Use the arrow keys and Enter to pick, Esc to close.
• Starting view: the saved pin, then the school, then the school's country, then Khartoum. It never opens at 0,0. Under a school, the school is drawn as a reference marker.
• Landing: picking a result, using the current location or tapping the map moves the map immediately. The address arrives when reverse geocoding answers. Drag the pin to adjust. The address line under the map is editable, so you can add a house number or nearest landmark.
• Arabic: map labels follow the page language. The RTL text plugin is armed before every map is created.
• Storage: address/city/state/country as before, plus latitude/longitude on School, Student, Teacher and Application.

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