University Course Scheduling System
A full-stack web application that builds Quchan University of Technology's weekly class timetable. Education staff upload the lessons and classrooms exported by the university's own system as Excel files; the application assigns every lesson to a suitable classroom automatically, and anyone can view, search, print or export the result. The entire interface is in Persian, right-to-left, on the Jalali calendar.
Presented as my Bachelor of Science final project in Computer Engineering at Quchan University of Technology, supervised by Dr. Mohamad-Hoseyn Sigari.
Overview
A full-stack web application that builds Quchan University of Technology's weekly class timetable. Education staff upload the lessons and classrooms exported by the university's own system as Excel files; the application assigns every lesson to a suitable classroom automatically, and anyone can view, search, print or export the result. The entire interface is in Persian, right-to-left, on the Jalali calendar.
Problem
Each term, hundreds of lessons have to fit into a limited set of rooms across six two-hour slots a day, Saturday to Thursday. Every room has its own capacity and special equipment, and some lessons run only in odd or even weeks. The timetable was assembled by hand in spreadsheets, which made it slow to build and easy to break.
Solution
Staff import the university's raw Excel export as-is, review the parsed lessons in a preview step, and save. A deterministic three-pass placement algorithm then assigns rooms: lessons that need special-equipment rooms are placed first, every lesson takes the smallest room that fits, and an odd-week and an even-week lesson can share a room. A manual slot editor lets staff adjust single slots and lists the lessons that found no room. The finished timetable is published read-only for students and faculty, with day and week views, fuzzy search, printing and Excel export.
Architecture
A Django 5 + Django REST Framework backend in a layered structure — services own the business logic, views stay thin — on PostgreSQL 14, with Redis for caching and rate-limit counters, served by gunicorn and WhiteNoise. Excel files are parsed and validated with pandas and openpyxl. The React 18 + TypeScript frontend (Vite, TanStack Query, Ant Design, Tailwind CSS) follows a feature-based structure, with Fuse.js for search and moment-jalaali for the Jalali calendar. Four roles — admin, education manager, education assistant and public visitor — are enforced on the server for every endpoint. Authentication uses JWT with refresh-token blacklisting on logout and per-IP login rate limiting. Docker Compose runs nginx, the backend, the frontend build, PostgreSQL and Redis, with nginx as the single entry point behind an edge proxy; a separate production compose file uses the host’s PostgreSQL.
Challenges
Making room assignment deterministic and safe: the whole placement run is a single atomic transaction, so a failed run leaves the previous timetable untouched. A 2026 refactor fixed the algorithm and made its output reproducible.
Placing scarce resources first — special-equipment lessons go in the first pass and every lesson takes the smallest room that fits — while letting odd-week and even-week lessons share a room.
Importing the university's raw Excel export exactly as it comes: validation and preprocessing feed a preview step, and an import either fully succeeds or rolls back, so a bad file never wipes existing data.
Separating what each role may do — for example, an education manager runs the whole schedule but may only add and edit assistants — and enforcing it on the server for every endpoint rather than in the UI.
Outcomes
Deployed for Quchan University of Technology at softcomp.ir, replacing the hand-built spreadsheet timetable with automatic room assignment and a public read-only schedule.
Covered by pytest and pytest-django on the backend, Vitest with Testing Library and MSW on the frontend, and Playwright end-to-end tests for auth, roles, CRUD, upload and preview, scheduling, search, responsive layout and real university data.
Fully documented: architecture, API reference, an algorithm specification with a worked example, the Excel format, deployment, environment variables, testing, a security checklist and a secret-rotation guide.
Lessons Learned
Admin override deserves first-class treatment — staff will always need to correct an automated decision, and the lessons that found no room must be visible, not silent.
Imports that touch live data must be all-or-nothing; a preview step plus a rollback turns a risky upload into a routine one.
Determinism matters as much as correctness: a scheduler that gives a different answer on each run cannot be trusted or debugged.
Error messages belong to the user’s language — every server error is written in Persian, and the UI shows the server’s own text instead of a generic failure.
