SchoolOS

Multi-tenant school management SaaS for Nigerian schools, built by Echoblaze.

SchoolOS gives every school its own tenant with six role-based portals — Principal, Teacher, Bursar, Secretary, Student, Parent — plus a platform-level Super Admin dashboard for onboarding, billing, and compliance across all schools.

---

Tech Stack

Layer	Tech
Framework	Next.js (App Router, Turbopack)
Language	TypeScript
Database / Auth	Supabase (PostgreSQL, Auth, Storage, Row-Level Security)
Styling	CSS Modules + CSS variables (no Tailwind)
Payments	Paystack (subaccount split payments — 97% to school, 3% platform fee)
Email	Resend
Push notifications	Web Push (VAPID)
Hosting	Vercel
PWA	Manifest + service worker (public/manifest.json, public/sw.js)

---

What's In This Repo

src/
├── app/
│   ├── splash/                    Cinematic 3D launch screen — plays once, then routes to select-school
│   ├── login/                    Access-code + password login (requires a school already selected)
│   ├── onboarding/stage-1..3/    3-stage onboarding (identity, password, NIN + docs)
│   ├── register-school/          Self-service school signup (Paystack registration)
│   ├── select-school/            Required school picker — gates access to /login; offers a
│   │                              "Continue with [school]" shortcut once one has been used before
│   ├── forgot-password/, reset-password/
│   ├── school-locked/            Shown when a school's subscription lapses
│   │
│   ├── dashboard/
│   │   ├── principal/            Students, staff, transfers, reports, school settings, banking/Paystack
│   │   ├── teacher/              Classes, attendance, gradebook
│   │   ├── bursar/               Invoices, fees, debtors, receipts, payment recording, reminders, export
│   │   ├── secretary/            Admin/records support
│   │   ├── student/              Grades, attendance, fees owed
│   │   └── parent/               Child(ren) overview, fee payments, attendance
│   │
│   │   Every role above also has an `ai/` route rendering the shared
│   │   `UniversalAIPage` — role-aware chat with persistent history, image
│   │   queries, and per-role rate limiting (see AI Assistant below).
│   │
│   ├── super-admin/              Platform-level dashboard (all schools)
│   │   ├── schools/              Full schools list (search/filter by status)
│   │   ├── school/[id]/          Per-school detail: overview, staff, payments, compliance, settings
│   │   ├── revenue/               Platform revenue view
│   │   └── settings/              Platform admin settings
│   │
│   ├── admin/                    School-level admin utilities
│   └── api/
│       ├── auth/, first-login/, onboarding/     Auth + onboarding endpoints
│       ├── principal/, bursar/, secretary/, parent/   Role-scoped actions
│       ├── super-admin/          create-school, manage-school (compliance, verification, locking)
│       ├── paystack/             create-subaccount (split payments), webhooks
│       ├── payments/, subscription/, trial/, currency/
│       ├── push/, notifications/  Web push subscriptions + delivery
│       ├── receipts/              PDF/receipt generation
│       ├── ai/, study-plan/       AI assistant — chat (`ai/chat`, with persisted history + image
│       │                          queries + rate limiting) and history (`ai/history`), plus study-plan
│       └── cron/                 Scheduled jobs (trial reminders, etc.)
│
├── hooks/
│   └── useVisualViewportHeight.ts  Tracks the true visible viewport height (mobile keyboard-aware);
│                                    used by full-height layouts like AI/Chat so a sticky input bar
│                                    stays pinned above the on-screen keyboard instead of scrolling off
│
├── lib/
│   ├── types.ts                  TypeScript types matching the DB schema
│   ├── signOutFlow.ts             Shared sign-out helper — snapshots the current school for the
│   │                              select-school "Continue with" pill, clears the active-school key,
│   │                              signs out of Supabase, and routes to /select-school (not /login)
│   └── supabase/
│       ├── client.ts              Browser client
│       ├── server.ts              Server client (cookie-based, respects RLS)
│       ├── admin.ts               Service-role client — server-only, bypasses RLS
│       └── ai_upgrade.sql         Migration: image_url/model_used columns on ai_messages, a
│                                   one-live-conversation-per-role index, RLS, and the
│                                   ai_check_rate_limit() function used by /api/ai/chat
└── middleware.ts                  Route guard — enforces onboarding stages + role-based routing (incl. /super-admin)

---

Core Concepts

Roles & Multi-Tenancy

Every profile belongs to a school_id and a role. Middleware and RLS both enforce that a user can only reach their own role's dashboard and their own school's data — no authenticated user can browse another school's or another role's pages.

App Entry & Session Flow

/splash              (cinematic launch screen, plays once)
  ↓
/select-school        (required — search or "Continue with [school]"; blocks /login without one)
  ↓
/login  (access code + temp password)
  ↓
/onboarding/stage-2   (identity confirmation + password change)
  ↓
/onboarding/stage-3   (NIN verification via Dojah + document upload)
  ↓
role dashboard

The onboarding_stage enum on the profile drives the last two steps; the middleware won't let a user skip ahead by URL. Separately, /login itself checks localStorage for a selected school on mount and redirects to /select-school if none is present — so the school step can't be bypassed by a direct link, bookmark, or back button either.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗