Mulberry House Vets — a deterministic scheduling system that respects nine constraint types, rebuilt from Python to production-grade TypeScript

Staff scheduling in a veterinary practice is a constraint-satisfaction problem with human consequences. Get it wrong and the reception desk is uncovered at morning peak. Get it right and 49 staff members have a rota they can plan around.

The challenge

Mulberry House Vets operated a staff scheduling system built in Python with FastAPI and SQLite — a system that worked, that its team understood, and that had been developed incrementally to handle the specific constraints of a veterinary practice. Those constraints are not trivial: nine hard constraints govern every valid schedule, covering role and site eligibility, date-specific and shift-specific unavailability, date-range unavailability (leave), contract day limits, coverage minima, lunch cover requirements, reception pairing rules (no two C-grade receptionists on the same shift), and exclusion of non-schedulable staff. The original Python scheduler satisfied all nine. The requirement was a rebuild in a modern stack — Next.js, TypeScript, Neon PostgreSQL, Drizzle ORM — with richer operational interfaces, CRUD across all input data, review links, PDF export, and calendar visualisation. The non-negotiable: the scheduling algorithm had to produce identical output for identical input. Determinism is correctness when your output is a rota.

The Blu Wingu approach

Blu Wingu designed and delivered the rebuild using the QUADRANT stack — Next.js 16 App Router, Neon serverless PostgreSQL, Drizzle ORM, NextAuth.js v5, Tailwind CSS 4, shadcn/ui, React Query, React Hook Form with Zod, Vitest, and Vercel.

Phase 1 was the algorithm port: the core scheduling generator (283 lines of production logic) ported from Python to TypeScript with full correctness preservation. The port was a translation under test, not a rewrite. Seedable deterministic random number generation (seedrandom) ensured identical seeds produce identical assignments — a property the test suite verifies directly. All nine hard constraints were carried across verbatim. The loader was rebuilt using Drizzle ORM to translate the database schema into the InputBundle type the generator expects, maintaining the same data contract as the Python version.

The database schema was designed as nine tables — six input tables (staff, shift template, coverage target, unavailability, unavailability range, fairness config) and three output tables (rota run, assignment, comment) — on Neon serverless PostgreSQL, chosen for a practice-scale application whose usage pattern is periodic rather than continuous.

Test coverage for Phase 1 was 100%. Ten Vitest tests verified the core correctness properties: same seed produces identical assignments; non-schedulable staff excluded; contract day limits respected; reception pairing constraints enforced. Tests were written before the port and passed after it — the port was not complete until the test suite was green.

The application architecture was designed for maintainability by a practice team: App Router with server components, server actions for mutations, React Query for server-state caching, and NextAuth.js v5 for authentication. The public review link is a separate route outside the protected application boundary.

The outcome

Phase 1 was completed on 12 December 2025 with 100% test coverage. The TypeScript scheduler produces deterministic output behaviourally identical to the Python implementation for the same input. All nine hard constraints are preserved. The database schema, application architecture, and test suite provide the foundation for the remaining phases — data migration, CRUD interfaces, rota generation and calendar, PDF export, and production deployment.

What’s defensible

Phase 1 completion on 12 December 2025 and 100% test coverage across 10 Vitest tests are verifiable from the repository history. The nine hard constraints are documented verbatim in the test suite. The QUADRANT stack choices and their rationale are documented in the project architecture record.