Overview
ClassSync is a web application that generates conflict-free timetables for schools and universities. Instead of building a schedule by hand and untangling clashes after the fact, ClassSync takes the institutional constraints - teachers, subjects, classrooms and availability - and produces a complete timetable in seconds.
The product pairs a Python scheduling engine with a web frontend and API backend. Generation is computationally heavy, so the solver runs asynchronously in Celery workers while the interface stays responsive.
How the generation engine works
The core solver is a greedy algorithm with a local-search repair pass.
- Prioritise the hardest lessons. Unscheduled lessons are ordered by a heuristic score. Teachers with heavy loads and other rigid constraints are placed first on an empty grid.
- Place greedily. Each lesson takes the first slot that satisfies every hard constraint: no double-booked teacher, room or class and no more than the allowed number of occurrences per day.
- Check constraints in constant time. In-memory matrices track occupancy across every dimension, so conflict detection is an O(1) lookup rather than repeated database work.
- Repair with min-conflicts search. If a few lessons cannot be placed, the engine force-places one into an occupied slot, evicts the lesson already there and cascades the swap until every lesson has a home.
The result is full placement with zero conflicts, including the awkward edge cases that a purely greedy pass tends to leave behind.
Validation before generation
Timetable generation is only as good as the data behind it. Before the solver runs, ClassSync validates the dataset and catches impossible constraints early - for example, a teacher assigned 40 periods but available for only 20. The master catalogs for faculties, subjects, classrooms and their associative constraints live in PostgreSQL, with foreign keys and cascading deletes protecting data integrity before the engine reads the state.
Setting up an institution
Access starts with a focused sign-in screen and the setup flow captures the structure of the school or university: faculties, subjects, teachers, classrooms and the rules that connect them.
Building and inspecting timetables
Generated timetables can be reviewed as a list or explored in a detailed grid. The grid makes clashes, free periods and room usage easy to scan at a glance.
Calendar and reports
A calendar view turns the timetable into a familiar weekly schedule, while the reports screen surfaces utilisation and load information for staff.
Architecture
- Asynchronous generation. The scheduling engine is decoupled from the API and runs in isolated Celery workers, with Redis as the message broker.
- Progress streaming. Jobs are queued and their progress is streamed back to the client so long runs never feel like a black box.
- PostgreSQL catalogs. Faculties, subjects, classrooms and constraints are modelled relationally with strict integrity rules.
- Docker Compose development. The full stack can be started with a single
docker compose up --build.