# rahib-khan0/timetable_scheduler architecture

> Architecture diagram of the GitHub repository rahib-khan0/timetable_scheduler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahib-khan0/timetable_scheduler
- Repository: https://github.com/rahib-khan0/timetable_scheduler

## Overview

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: [`backend_FastAPI/services/scheduler/scheduler_engine.py`](https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/services/scheduler/scheduler_engine.py) (Scheduler Engine), [`backend_FastAPI/api`](https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/api) (Domain APIs), [`backend_FastAPI/db/models`](https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/db/models) (ORM Models), [`fronend_React/src/pages`](https://github.com/rahib-khan0/timetable_scheduler/tree/main/fronend_React/src/pages) (Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React UI"]
  node_frontend_app["App Shell<br/>React SPA<br/>[App.jsx]"]
  node_frontend_pages["Pages<br/>UI screens"]
  node_frontend_api["API Client<br/>axios layer<br/>[index.js]"]
  node_frontend_layout["Protected Layout<br/>routing shell"]
end

subgraph group_api["HTTP API"]
  node_api_router["API Routes<br/>FastAPI routers"]
  node_api_auth["Auth API<br/>login and tokens<br/>[auth.py]"]
  node_api_domain["Domain APIs<br/>resource routes"]
end

subgraph group_services["Business Services"]
  node_services_import["Import Service<br/>Excel ingestion"]
  node_services_fetch["Raw Loader<br/>data fetch<br/>[raw_data_loader.py]"]
  node_services_scheduler["Scheduler Engine<br/>CP-SAT workflow"]
  node_services_constraints["Constraints<br/>model rules"]
  node_services_storage["Result Storage<br/>timetable persistence<br/>[storage.py]"]
  node_services_timetable["Timetable Output<br/>format/export"]
end

subgraph group_db["Persistence"]
  node_db_models[("ORM Models<br/>SQLAlchemy domain")]
  node_db_session[("DB Session<br/>engine/session<br/>[session.py]")]
end

subgraph group_core["Security Core"]
  node_core_security["Security Core<br/>JWT/security"]
  node_core_deps["Dependencies<br/>FastAPI deps<br/>[dependencies.py]"]
end

node_external_solver{{"OR-Tools<br/>optimization engine"}}

node_frontend_app -->|"renders"| node_frontend_layout
node_frontend_layout -->|"navigates"| node_frontend_pages
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_api -->|"requests"| node_api_router
node_api_router -->|"auth"| node_api_auth
node_api_router -->|"domain"| node_api_domain
node_api_auth -->|"uses"| node_core_security
node_api_domain -->|"injects"| node_core_deps
node_api_domain -->|"imports"| node_services_import
node_api_domain -->|"schedules"| node_services_scheduler
node_api_domain -->|"exports"| node_services_timetable
node_services_import -->|"writes"| node_db_models
node_services_scheduler -->|"loads"| node_services_fetch
node_services_scheduler -->|"applies"| node_services_constraints
node_services_scheduler -->|"solves"| node_external_solver
node_services_scheduler -->|"stores"| node_services_storage
node_services_storage -->|"persists"| node_db_models
node_services_timetable -->|"reads"| node_db_models
node_db_models -->|"uses"| node_db_session
node_core_deps -->|"provides"| node_db_session
node_services_constraints -->|"feeds"| node_services_scheduler

click node_frontend_app "https://github.com/rahib-khan0/timetable_scheduler/blob/main/fronend_React/src/App.jsx"
click node_frontend_pages "https://github.com/rahib-khan0/timetable_scheduler/tree/main/fronend_React/src/pages"
click node_frontend_api "https://github.com/rahib-khan0/timetable_scheduler/blob/main/fronend_React/src/api/index.js"
click node_frontend_layout "https://github.com/rahib-khan0/timetable_scheduler/tree/main/fronend_React/src/components/layout"
click node_api_router "https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/api"
click node_api_auth "https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/api/auth.py"
click node_api_domain "https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/api"
click node_core_security "https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/core"
click node_core_deps "https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/core/dependencies.py"
click node_db_models "https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/db/models"
click node_db_session "https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/db/session.py"
click node_services_import "https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/services/upload_data"
click node_services_fetch "https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/services/fetch_data/raw_data_loader.py"
click node_services_scheduler "https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/services/scheduler/scheduler_engine.py"
click node_services_constraints "https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/services/scheduler/constraints_hard"
click node_services_storage "https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/services/scheduler/storage.py"
click node_services_timetable "https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/services/timetable"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_pages,node_frontend_api,node_frontend_layout toneBlue
class node_api_router,node_api_auth,node_api_domain toneAmber
class node_services_import,node_services_fetch,node_services_scheduler,node_services_constraints,node_services_storage,node_services_timetable toneMint
class node_db_models,node_db_session toneRose
class node_core_security,node_core_deps toneIndigo
class node_external_solver toneNeutral
```

## Components

### React UI

Single-page dashboard for login, data management, import, and timetable review.

- [App Shell](https://github.com/rahib-khan0/timetable_scheduler/blob/main/fronend_React/src/App.jsx): React SPA · Top-level client shell and routing container. · `fronend_React/src/App.jsx`
- [Pages](https://github.com/rahib-khan0/timetable_scheduler/tree/main/fronend_React/src/pages): UI screens · Role-gated pages for dashboard, master data, import, scheduler, and timetable views. · `fronend_React/src/pages`
- [API Client](https://github.com/rahib-khan0/timetable_scheduler/blob/main/fronend_React/src/api/index.js): axios layer · Centralized frontend-to-backend request wrapper. · `fronend_React/src/api/index.js`
- [Protected Layout](https://github.com/rahib-khan0/timetable_scheduler/tree/main/fronend_React/src/components/layout): routing shell · Authenticated dashboard layout and route guard. · `fronend_React/src/components/layout`

### HTTP API

FastAPI controllers, auth, and domain routes.

- [API Routes](https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/api): FastAPI routers · Domain-oriented route modules for auth, master data, import/export, scheduler, and timetable. · `backend_FastAPI/api`
- [Auth API](https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/api/auth.py): login and tokens · Authentication endpoints and login flow. · `backend_FastAPI/api/auth.py`
- [Domain APIs](https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/api): resource routes · 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](https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/services/upload_data): Excel ingestion · Parses spreadsheet input into academic master data. · `backend_FastAPI/services/upload_data`
- [Raw Loader](https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/services/fetch_data/raw_data_loader.py): data fetch · Loads normalized raw academic data for downstream processing. · `backend_FastAPI/services/fetch_data/raw_data_loader.py`
- [Scheduler Engine](https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/services/scheduler/scheduler_engine.py): CP-SAT workflow · Orchestrates timetable generation from data organization to solution storage. · `backend_FastAPI/services/scheduler/scheduler_engine.py`
- [Constraints](https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/services/scheduler/constraints_hard): model rules · Hard and soft scheduling constraints across faculty, rooms, groups, availability, and sessions. · `backend_FastAPI/services/scheduler/constraints_hard`
- [Result Storage](https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/services/scheduler/storage.py): timetable persistence · Stores solver output and timetable versions back into the database. · `backend_FastAPI/services/scheduler/storage.py`
- [Timetable Output](https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/services/timetable): format/export · Formats schedules for display and exports Excel timetable files. · `backend_FastAPI/services/timetable`

### Persistence

SQLAlchemy models and database session/base setup.

- [ORM Models](https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/db/models): SQLAlchemy domain · User, faculty, room, course, mapping, timetable, and special-class entities. · `backend_FastAPI/db/models`
- [DB Session](https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/db/session.py): engine/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](https://github.com/rahib-khan0/timetable_scheduler/tree/main/backend_FastAPI/core): JWT/security · Token creation, validation, password/security helpers, and request dependencies. · `backend_FastAPI/core`
- [Dependencies](https://github.com/rahib-khan0/timetable_scheduler/blob/main/backend_FastAPI/core/dependencies.py): FastAPI deps · Shared database-session and current-user dependency wiring. · `backend_FastAPI/core/dependencies.py`

### Other components

- **OR-Tools**: optimization engine · External CP-SAT solver used to compute feasible and optimized schedules.

## Connections

- 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.
