Getting a school set up
What a school has to have in place before EduSpaze is useful to it, how the platform walks them through it, and when it steps out of the way. Last updated 2026-09-06.
1. The shape of it
A school signing in for the first time lands on /school/start, not the dashboard. It stays the first screen until somebody says the school is set up, or skips. Both decisions are reversible from School Settings, and skipping loses nothing.
The redirect happens only from /school. Every other page stays reachable, because the checklist's own links go to them — a checklist that traps you on itself is a worse first experience than no checklist.
Only somebody holding school.onboarding VIEW is redirected. A teacher signing in on day one goes straight to their dashboard; setting the school up is not their job.
2. What we need from a school
Eleven steps in four phases. Essential steps must be done before the school can mark itself set up; optional ones never block it.
Your school
| Step | Essential | Why |
|---|---|---|
| Complete the school profile | yes | Segment, size, curriculum and country are what every recommendation is matched on. A thin profile gets thin matches. |
| Academic year and terms | yes | Without them the platform guesses a calendar year, which is wrong for a September school — and that guess is the label vendors see on every class. Term dates also open the termly checklist. |
| Verified email domains | yes | Staff sign-in is matched to the school's domains. SSO with Google or Microsoft sits on top and is optional; passwords keep working either way. |
Your people
| Step | Essential | Why |
|---|---|---|
| Invite colleagues | yes | One account is a single point of failure. At least one other person, with a role that says what they may do. |
| Bring in pupils | yes | Import the roster or connect the SIS. Pupil ids come from the school's own system and are never renumbered. |
| Classes, with pupils in them | yes | Classes are how a vendor places a pupil and how a teacher reaches their own group. A pupil in no class is invisible to both. |
| Connect the student information system | no | The roster refreshes itself on a schedule instead of by hand (docs/sis-sync.md). |
What you need
| Step | Essential | Why |
|---|---|---|
| The needs survey | yes | What the platform reasons from: what the school already runs, what is missing, the budget cycle, who decides. Nothing useful is recommended before it. |
| Look at your recommendations | yes | Matches appear as soon as the survey is in. Answering a few sharpens the next set. |
When you are ready
| Step | Essential | Why |
|---|---|---|
| First challenge statement | no | A named problem, not a category browse, is what gets a specific proposal rather than a brochure. The highest-signal thing a school does here. |
| Decide about parent access | no | Guardians see how long their own child spent in an app, never what they did. Off until the school turns it on. |
3. Done means done
A step is complete because the work is complete, observed from the school's own records: pupils exist, a term exists, the survey was answered, a colleague has an account. Not because somebody ticked a box.
A checklist that can be ticked without doing the work is a checklist that lies, and the school finds out weeks later when a vendor cannot place its pupils. tests/onboarding.test.ts refuses a manual tick on any observable step.
Two steps are exceptions, and honest ones: looking at your recommendations and deciding parent access is not for you leave no trace, so both are marked by hand.
Each step also shows *where the school actually stands* — "3 of 4 details, 2 curriculums", "12 classes, nobody in them" — rather than a bare tick. The gap is the useful part.
4. Finishing, skipping, coming back
| Action | Effect |
|---|---|
| We're set up | Available once every essential is done. The dashboard becomes the landing screen. |
| Skip for now | Available always. Same effect, no judgement, nothing lost. |
| Show it on sign-in again | School Settings → Getting set up. Puts the checklist back. |
Finishing does not rewrite history: the stored record says when and by whom, and the steps keep reporting honestly afterwards, so a school that marked itself complete with a half-filled profile still sees the profile step as incomplete when it comes back.
Everything lands on the school's own audit chain: school.onboarding_step, school.onboarding_completed, school.onboarding_skipped, school.onboarding_reopened.
5. Permissions
| Module | VIEW | EDIT |
|---|---|---|
school.onboarding | see the checklist and where the school stands | tick a manual step, finish, skip, reopen |
Held by the school administrator role. Anyone else works through the same portal without ever seeing the checklist, and without being redirected to it.
6. Adding a step
A step is an entry in ONBOARDING_STEPS (lib/school/onboarding.ts) plus a line in the signal gather. The harness holds two rules: every step must link somewhere a module actually covers, and every step must say why it matters rather than only what to do — a checklist of instructions with no reasons is one people click through rather than act on.