School OS

The trust engine for schools. Peace of mind for parents.

School OS is a mobile-first, Apple-polished school management platform built on one premise: parents want to know their child is safe, and schools want to prove it.

It is not a generic ERP. It is a trust and communication engine for affordable private schools (roughly 200–2,000 students) — starting with Smart Attendance and WhatsApp alerts, then expanding into communication, academics, finance, and AI-assisted teaching tools.

This repository is the production monorepo for that product: Bun, Turborepo, Next.js, Expo, NestJS, shared packages, Docker, and CI.

100-second tour

Principal and teacher views of the web app, recorded from the running stack with the seeded demo school (1920×1200, H.264). Download the video · screen-by-screen map in product-tour.

The killer demo

Teacher scans a student's QR code at the school gate.
→ Within seconds, the parent's phone buzzes on WhatsApp:
  "Rohan has arrived safely at school. 8:17 AM."

Principal's dashboard updates in real time:
  247 students in · 3 absent · 1 late

That loop — scan → parent alert → live dashboard — is Phase 1. Everything else builds on that trust signal.

Core philosophy

Research-informed messaging (2026): Use the official WhatsApp Business Cloud API (not personal WhatsApp or unofficial gateways). Collect explicit parent opt-in, route all minor communication through guardians, prefer utility templates for transactional alerts, respect quiet hours, and let schools tune frequency (exception alerts vs. weekly digests) to avoid notification fatigue.

Who it's for

Product modules (roadmap)

Detailed backend phases: production-roadmap · Full architecture: product-system-design · Vision brief: product-vision

Smart Attendance (Phase 1 detail)

Face recognition stays optional and off by default until consent, legal review, and a pilot require it.

Built today

The web app is rebuilt screen by screen to the School OS Figma file, on live data from the Nest API. Parent mobile and WhatsApp delivery are still on the roadmap; screens that depend on them say so instead of showing sample data.

--- | --- | | Monorepo (Bun, Turbo, oxlint, oxfmt, Lefthook, CI) | ✅ | | Web admin shell + marketing (apps/web) | ✅ | | Expo mobile scaffold (apps/mobile) | ✅ | | NestJS API spine — auth, sessions, MFA, passkeys, profiles (apps/nest-api) | ✅ | | Billing hooks — Stripe / Razorpay (apps/nest-api) | ✅ | | Docs site (apps/docs) | ✅ | | Tenants, academic structure, students (table + ID cards), guardians, staff | ✅ | | Attendance (homeroom), teacher dashboard + my classes roster (table + ID cards) | ✅ | | Homework, assessments, test planner (teacher/admin) | ✅ | | Parent/student homework & test views, WhatsApp pipeline | 🔜 Phase 1–2 per roadmap (parent My children ID cards + homework live) |

What's in the box (technical)

Shared packages (@school-os/ui, @school-os/logger, TypeScript configs), Docker Compose, Dev Container, Lefthook hooks, and CI/CD pipelines are included out of the box.

Positioning vs. the detailed spec

Quick start

Prerequisites: Bun 1.4.2 (pinned with mise: mise install) · Git · optional Docker Compose v2.20+ and Rust (for apps/rust)

git clone https://github.com/rabtx/school-os.git
cd school-os
bun install
bun run prepare   # install git hooks (recommended)
bun run dev

Run a single app:

bun --cwd=apps/web run dev
bun --cwd=apps/nest-api run dev
bun --cwd=apps/mobile run dev
bun --cwd=apps/docs run dev

Before pushing changes:

bun run lint && bun run format && bun run typecheck

Architecture

┌─────────────┐   ┌─────────────┐
│  apps/web   │   │ apps/mobile │
│  (Next.js)  │   │   (Expo)    │
└──────┬──────┘   └──────┬──────┘
       │                 │
       └────────┬────────┘
                ▼
       ┌─────────────────┐
       │  apps/nest-api  │  (AI layer in TypeScript, planned)
       │    (NestJS)     │
       └────────┬────────┘
                ▼
       ┌─────────────────┐     ┌──────────────────┐
       │ Postgres / Neon │     │ WhatsApp / SMS /   │
       └─────────────────┘     │ email (Phase 1+)   │
                               └──────────────────┘

packages/ui · packages/logger · packages/typescript-config

Core product loop (target):

Student arrives → attendance event → parent alert → live dashboard → AI risk signal

Engineering loop (target):

Write to Postgres + outbox in one transaction → worker delivers notifications & realtime → idempotent, auditable side effects

Import boundaries and naming rules: bun run architecture:check.

Monorepo layout

school-os/
├── apps/
│   ├── web/          Next.js admin + marketing + auth
│   ├── mobile/       Expo Router mobile app
│   ├── nest-api/     NestJS production API
│   ├── docs/         Fumadocs documentation site
│   └── rust/         Optional Rust/Axum demo
├── packages/
│   ├── ui/           Shared shadcn-style components + tokens
│   ├── logger/       Structured logger (TS + Rust)
│   └── typescript-config/
├── docker/           Compose fragments (Postgres, Nest, web)
├── scripts/          Bash + Python utilities
├── .github/workflows CI, CD, security
└── .devcontainer/    Reproducible dev environment

Commands

Tooling

• Bun workspaces + Turborepo orchestration
• oxlint and oxfmt for TS/JS lint and format (tabs, line width 100)
• Lefthook pre-commit and commit-msg hooks (Conventional Commits, lowercase)
• Bash: ShellCheck + shfmt · Python: Ruff · Rust: rustfmt + clippy

Docker

cp env.docker.example .env
docker compose up -d --build

Optional profile: docker compose --profile rust up -d --build.

See docker/README.md and /docs/docker.

Deploy

Guide: /docs/deploy (apps/docs/content/docs/deploy.mdx).

Dev Container

Reopen in Container for Bun, Rust, Python/Ruff, and Bash lint tools pre-installed.

Reopen in Container → bun run prepare → bun run dev

See .devcontainer/README.md.

Documentation

bun --cwd=apps/docs run dev

Key routes (http://localhost:3002/docs/…):

• product-tour — the intro video and every screen by role
• product-vision — trust engine positioning and feature spec
• quick-start — setup and first run
• production-roadmap — phased NestJS build plan
• product-system-design — data model, security, APIs
• architecture — boundaries and conventions
• docker · deploy

Also see PROJECT.md, DESIGN.md, AGENTS.md, CHANGELOG.md.

Monetization (if operated as SaaS)

Contributing

1. Fork and clone the repo.
2. bun install && bun run prepare
3. Create a branch and make changes.
4. Run bun run preflight before opening a PR.
5. Use Conventional Commits — lowercase subjects, e.g. feat(attendance): add qr scan endpoint.

License

Dual-licensed under MIT or Apache-2.0: LICENSE-MIT, LICENSE-Apache-2.0.

Thanks ❤️