Onboarding & Setup

One-line: getting a new school from “created” to “usable” — a super-admin-driven seeding path plus a guided setup wizard, so a tenant starts with its academic structure already in place.

What it does

A new tenant needs its academic backbone before staff can do anything useful: the school’s units/branches, the first academic year and terms, grades, classes, subjects, and initial admin accounts. Onboarding covers two paths to get there:

Scripted / white-glove seeding — operators seed a school in bulk from a data file, for hands-on pilot onboarding.
Guided setup wizard — a structured in-app flow (/api/school-setup/*) that walks through school info → first academic year → grades → classes.

When done, the tenant is marked is_setup_complete = true and the app opens up.

Who uses it

NexSchool operators (super-admin) run both paths. The structured school-setup flow is super-admin-only — the tenant Admin role no longer carries school_setup.* (migration 064). School admins and sub-admins can neither see nor run setup.
Operators drive this from the panel.

Key concepts

Scripted seeding — a seed script (server/scripts/seed_school.py) consumes a YAML description of the school and creates the structure in one pass. Ideal for pilots where NexSchool sets the school up for them.
Setup wizard — the guided UI flow, kept behind a feature flag (NEXT_PUBLIC_ENABLE_SCHOOL_SETUP) while it stabilises.
is_setup_complete — the tenant flag that gates the app; super-admins bypass the “setup complete” requirement so they can work during setup.

How it works

Operator creates tenant + assigns plan (panel)
        │
        ├─ Path A: seed_school.py + school.yaml  → bulk-create units/years/grades/classes/subjects/admins
        └─ Path B: school-setup wizard (super-admin) → step-by-step create
        │
        ▼
tenant.is_setup_complete = true  → school staff can use admin-web

Rules & edge cases

School-setup endpoints are gated by school_setup.read / school_setup.manage and reachable only via super-admin god-mode.
The wizard is opt-in behind NEXT_PUBLIC_ENABLE_SCHOOL_SETUP; the scripted path is the primary route for pilot onboarding.
Seeding is tenant-scoped and idempotent-minded — designed to build a coherent starting structure, not to run repeatedly against a populated tenant.

Where it lives

Backend: server/modules/school_setup/, server/scripts/seed_school.py
Panel: onboarding / login-as-tenant actions
Related: Academics (the structure being seeded), Control plane

Subscriptions & Plans Overview