How rahib-khan0/timetable_scheduler works
1. This repository is a two-tier academic timetable system: a FastAPI backend in backend_FastAPI/ and a React/Vite frontend in fronend_React/. The backend owns authentication, data import/export, database access, and timetable generation; the frontend is a dashboard for managing academic entities and triggering scheduling.
2. The backend is organized around three major boundaries: HTTP API routes in backend_FastAPI/api/, domain/business services in backend_FastAPI/services/, and persistence models/session code in backend_FastAPI/db/. This separation matters because most complex logic is not in the route handlers; routes act mainly as controllers that call service modules and return schemas/DTOs.
3. Authentication is handled through backend_FastAPI/api/auth.py and the core/ package. JWT creation/validation and security helpers live in core/jwt.py and core/security.py, while core/dependencies.py likely supplies authenticated-user and DB-session dependencies. The README indicates role-based access and institute isolation, so auth is a core architectural boundary rather than a thin add-on.
4. The database layer uses SQLAlchemy models under backend_FastAPI/db/models/ with a PostgreSQL backend. The model set reflects the scheduling domain: users, faculty, rooms, courses, department/semester mappings, timetable versions, timetable entries, special classes, and course components. The presence of session.py, base.py, and db/base.py suggests a conventional ORM setup with a centralized session factory and declarative base.
5. A notable architectural feature is multi-tenancy via PostgreSQL schema-per-institute. That means timetable and master-data records are not just filtered by institute ID at the application layer; the deployment model assumes separate database schemas as hard boundaries between institutions. This affects every data access path, especially import, scheduling, and export.
6. Data ingestion is Excel-driven. backend_FastAPI/services/upload_data/ contains parsers for faculty, rooms, courses, department-semester data, and special classes, with excel_parser.py coordinating the import flow. The templates in backend_FastAPI/templates/ and sample files in backend_FastAPI/utils/ indicate the system expects structured spreadsheet input as the canonical onboarding format.
7. The scheduling engine is the most important subsystem. backend_FastAPI/services/scheduler/ contains OR-Tools-based CP-SAT scheduling logic, split into data organization, session building, variable creation, hard/soft constraints, solver orchestration, infeasibility diagnosis, solution extraction, storage, and pretty-printing. This is the computational core that transforms imported academic data into conflict-free timetables.
8. The scheduler’s constraint model is explicitly layered. Hard constraints are separated into faculty, room, group, availability, and session constraints, while soft constraints include preferences such as room choice and workload balancing. This architecture implies that the engine can report infeasibility when the hard constraint set cannot be satisfied and can also optimize for quality among feasible schedules.
9. Generated schedules are persisted back to the database and also exposed for presentation/export. The modules scheduler/storage.py, store_solutions_in_DB.py, and services/timetable/formatter.py / export_excel.py indicate a pipeline from solver output to stored timetable versions and formatted timetable views. The exported .xlsx files under backend_FastAPI/exports/ show that Excel is both an input and an output artifact.
10. API routing is domain-oriented rather than generic CRUD only. The route modules include courses.py, faculty.py, rooms.py, departments.py, timetable.py, scheduler.py, data_import.py, data_export.py, drop.py, and debug.py. This suggests separate endpoints for master data management, schedule generation, timetable retrieval/editing, and administrative diagnostics.
11. The frontend is a role-gated single-page application built with React, Axios, and Tailwind. src/pages/ contains dedicated screens for login, registration, dashboard, courses, departments, faculty, rooms, import, scheduler, and timetable views. ProtectedRoute.jsx and AppLayout.jsx show that authentication state controls access and the dashboard is the central UI shell.
12. Frontend-to-backend communication is likely centralized through src/api/index.js, with store-level state management in src/store/. The UI boundary is therefore a thin client over the FastAPI service, not an independently rich application server. The frontend’s main responsibility is collecting data, presenting timetable results, and invoking backend operations.
13. There are also repository-level assets for local operation and handoff: .bat startup scripts, a Postman collection in utils/, SQL/backup files, and a static home/ page. These are supporting artifacts rather than core runtime components, but they indicate that the system is intended to be run locally and exercised through API clients as well as the UI.
14. For an architecture diagram, the key flows are: user interacts with React UI; UI calls FastAPI endpoints; FastAPI authenticates the request and loads/writes PostgreSQL data; import endpoints parse Excel into domain models; scheduler endpoints assemble academic data and invoke OR-Tools; solver output is validated, stored, and exported as timetable files/views. The main system boundaries are frontend, API/auth layer, domain services, ORM/database, and the external optimization engine.
Main entry points: scheduler_engine.py Scheduler Engine · api Domain APIs · models ORM Models · pages Pages
Components 18
React UI
Single-page dashboard for login, data management, import, and timetable review.
- App Shell · Top-level client shell and routing container.
fronend_React/src/App.jsx - Pages · Role-gated pages for dashboard, master data, import, scheduler, and timetable views.
fronend_React/src/pages - API Client · Centralized frontend-to-backend request wrapper.
fronend_React/src/api/index.js - Protected Layout · Authenticated dashboard layout and route guard.
fronend_React/src/components/layout
HTTP API
FastAPI controllers, auth, and domain routes.
- API Routes · Domain-oriented route modules for auth, master data, import/export, scheduler, and timetable.
backend_FastAPI/api - Auth API · Authentication endpoints and login flow.
backend_FastAPI/api/auth.py - Domain APIs · Courses, faculty, rooms, departments, timetable, import/export, drop, and debug endpoints.
backend_FastAPI/api
Business Services
Import, scheduling, data formatting, and timetable workflows.
- Import Service · Parses spreadsheet input into academic master data.
backend_FastAPI/services/upload_data - Raw Loader · Loads normalized raw academic data for downstream processing.
backend_FastAPI/services/fetch_data/raw_data_loader.py - Scheduler Engine · Orchestrates timetable generation from data organization to solution storage.
backend_FastAPI/services/scheduler/scheduler_engine.py - Constraints · Hard and soft scheduling constraints across faculty, rooms, groups, availability, and sessions.
backend_FastAPI/services/scheduler/constraints_hard - Result Storage · Stores solver output and timetable versions back into the database.
backend_FastAPI/services/scheduler/storage.py - Timetable Output · Formats schedules for display and exports Excel timetable files.
backend_FastAPI/services/timetable
Persistence
SQLAlchemy models and database session/base setup.
- ORM Models · User, faculty, room, course, mapping, timetable, and special-class entities.
backend_FastAPI/db/models - DB Session · Centralized SQLAlchemy session factory and declarative base.
backend_FastAPI/db/session.py
Security Core
JWT, security helpers, and dependencies used across the backend.
- Security Core · Token creation, validation, password/security helpers, and request dependencies.
backend_FastAPI/core - Dependencies · Shared database-session and current-user dependency wiring.
backend_FastAPI/core/dependencies.py
Other components
- OR-Tools · External CP-SAT solver used to compute feasible and optimized schedules.
Connections 21
- App Shell → Protected Layout: renders · App is wrapped in authenticated dashboard layout.
- Protected Layout → Pages: navigates · Layout routes users to role-specific pages.
- Pages → API Client: calls · Pages invoke the shared API client for backend operations.
- API Client → API Routes: requests · Frontend sends HTTP requests to FastAPI routers.
- API Routes → Auth API: auth · Authentication routes handle login and token issuance.
- API Routes → Domain APIs: domain · Resource routes manage academic data and timetable actions.
- Auth API → Security Core: uses · Auth flow relies on JWT and security helpers.
- Domain APIs → Dependencies: injects · Routes use shared dependencies for sessions and current user.
- Domain APIs → Import Service: imports · Import endpoints delegate spreadsheet parsing and ingestion.
- Domain APIs → Scheduler Engine: schedules · Scheduler endpoints trigger timetable generation workflows.
- Domain APIs → Timetable Output: exports · Timetable endpoints format and return schedule views/files.
- Import Service → ORM Models: writes · Imported master data becomes persistent domain records.
- Scheduler Engine → Raw Loader: loads · Scheduler assembles normalized raw data before solving.
- Scheduler Engine → Constraints: applies · Constraint modules define the feasible timetable search space.
- Scheduler Engine → OR-Tools: solves · Scheduler delegates optimization to OR-Tools CP-SAT.
- Scheduler Engine → Result Storage: stores · Generated schedules are persisted as timetable versions and entries.
- Result Storage → ORM Models: persists · Storage layer writes solver output through ORM models.
- Timetable Output → ORM Models: reads · Formatting and export read timetable data from the database.
- ORM Models → DB Session: uses · ORM models are managed through the shared session/base setup.
- Dependencies → DB Session: provides · Dependencies expose database sessions to API handlers.
- Constraints → Scheduler Engine: feeds · Constraint results feed back into the solver orchestration.