The in house timetable engine

Why we built it

This is the in house timetable engine the studio runs on. Timetabling looks like a small problem until you look at it. Real schools have qualification rules, daily and weekly caps, room capacity, curriculum bindings, teacher preferences, workload fairness, and the absolute prohibition on a teacher being in two rooms at once. Off the shelf timetabling tools handle the easy half. The hard half (substitute assignment, versioned rollback, curriculum variations across CBSE, ICSE, and state boards) is where they fall apart.

This engine is the proof that a small team can ship the whole stack: solver, platform, API, front end, mobile scaffold. Built end to end in our own monorepo. Modern English School is the institution we use to validate the system in production like conditions; they are not a paying client. The engineering transfers; the engine itself is the worked example.

Concentric layers

Engine. A pure TypeScript scheduling library with zero I/O and zero side effects. Two level CSP backtracking: subject selection from syllabus bindings using a most remaining values heuristic, then teacher plus room assignment sorted by least loaded teacher. Seven hard constraints, four soft. The engine returns either a valid timetable or a structured explanation of why no solution exists; never a silent failure.

Platform. Multi tenant Postgres with row level security. Every table carries tenant_id. The API sets SET LOCAL app.current_tenant_id per request from the JWT claim. Fastify routes, role based access control across Admin, Teacher, Student, and Parent. Versioned snapshots with diff and rollback. Canonical error envelope, x-support-ref header on every response, audit trail of read and write events.

Surface. React 19 + Vite + Tailwind 4. Five themes (obsidian, clarity, seijaku, plus high contrast obsidian-hc and clarity-hc). PWA enabled. Role aware views: administrators see full editors; teachers see only their schedules; students and parents access read only schedules matched to their enrollment. A Capacitor scaffold for iOS and Android packaging.

What we measure

183 unit and integration tests passing across 18 test files. A stress bench that exercises the solver at 1,500 to 8,000 variables. The full engine validated on a 36 variable fixture: zero conflicts, all invariants pass. Substitution ranking tested across qualification, availability, and load scoring. Curriculum validation tested across CBSE requirements, ICSE split sciences, and state board permissive sets.

Earlier figures published on the live site ("30.8k LOC, 3.6s solve at 5k variables, 94% allotment") came from a previous Python + OR Tools experiment. The current TypeScript engine has not yet had a published stress bench run; we replace those numbers here once it does.

What sits on top of this work

The timetable engine plus the multi tenant platform are the load bearing primitives behind Arka, our productised K-12 school operating system. The same engine handles timetabling, attendance, and the academic calendar surface inside Arka.

Why it matters for an engagement

If you are evaluating us to build a vertical platform with hard constraints, regulated tenant isolation, and a role aware surface, the work here is the proof. The architecture transfers; the engine does not. We do not sell the engine; we sell the engineering that produced it.

Further reading

• OR Tools vs FET vs commercial timetabling: an honest comparison, the decision rationale that preceded this build.
• Multi tenant Postgres with Row Level Security: a working pattern, the isolation pattern this platform uses.