# imatomic7407/timetable-studio architecture

> Architecture diagram of the GitHub repository imatomic7407/timetable-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imatomic7407/timetable-studio
- Repository: https://github.com/imatomic7407/timetable-studio

## Overview

Timetable Studio builds a school-wide weekly schedule, lets a registrar edit and publish it, then supports daily teacher attendance, leave, and class cover. The graph follows that user journey through the app, API, shared timetable model, and solver, with separate branches for teacher access and administration. Several implementation files were not sampled; documented capabilities are retained, while edges relying only on unsampled wiring are omitted or marked unverified.

Main entry points: [`backend/src/http/server.ts`](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/http/server.ts) (HTTP server), [`backend/src/services/timetables/service.ts`](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/timetables/service.ts) (Timetable lifecycle), [`app/src/data/api/apiClient.ts`](https://github.com/imatomic7407/timetable-studio/blob/main/app/src/data/api/apiClient.ts) (API client), [`app/src/App.tsx`](https://github.com/imatomic7407/timetable-studio/blob/main/app/src/App.tsx) (App entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Web app"]
  node_app_entry["App entry<br/>[App.tsx]"]
  node_store["App state<br/>[store.tsx]"]
  node_editor["Timetable editor<br/>[EditorPage.tsx]"]
  node_rules_ui["Rule manager<br/>[RulesPage.tsx]"]
  node_teacher_portal["Teacher portal<br/>[TeacherApp.tsx]"]
  node_api_client["API client<br/>[apiClient.ts]"]
  node_admin_ui["Administration<br/>[UsersPage.tsx]"]
end

subgraph group_backend["API and services"]
  node_http_server["HTTP server<br/>[server.ts]"]
  node_timetable_routes["Timetable routes<br/>[timetables.ts]"]
  node_timetable_service["Timetable lifecycle<br/>[service.ts]"]
  node_timetable_store[("Timetable persistence<br/>[repository.ts]")]
end

subgraph group_timetable["Timetable engine"]
  node_shared_core["Shared timetable model<br/>[types.ts]"]
  node_grid_rules["Grid and rule checks<br/>[grid.ts]"]
  node_solver_input["Solver input<br/>[solverInput.ts]"]
  node_solver_engine["Schedule solver<br/>[engine.py]"]
  node_solver_v2["Solver v2<br/>[build.py]"]
end

subgraph group_operations["Daily operations"]
  node_attendance["QR attendance<br/>[attendance.ts]"]
  node_leave_cover["Leave and cover<br/>[cover.ts]"]
  node_daily_ui["Daily operations UI<br/>[AttendancePage.tsx]"]
end

subgraph group_platform["Access and administration"]
  node_auth_service["Authentication<br/>[auth.ts]"]
  node_auth_gate["Permission gates<br/>[auth.ts]"]
  node_audit["Audit trail<br/>[audit.ts]"]
  node_db[("Application database<br/>[client.ts]")]
end

node_registrar(("Registrar"))
node_teacher(("Teacher"))

node_registrar -->|"uses"| node_app_entry
node_teacher -->|"uses"| node_app_entry
node_app_entry -->|"reads state"| node_store
node_app_entry -->|"routes teachers"| node_teacher_portal
node_registrar -->|"edits schedule"| node_editor
node_registrar -->|"manages rules"| node_rules_ui
node_teacher -->|"views week"| node_teacher_portal
node_editor -.->|"requests data"| node_api_client
node_rules_ui -.->|"requests rules"| node_api_client
node_teacher_portal -.->|"requests data"| node_api_client
node_api_client -->|"sends requests"| node_http_server
node_http_server -->|"mounts routes"| node_timetable_routes
node_timetable_routes -.->|"dispatches"| node_timetable_service
node_timetable_service -->|"maps records"| node_timetable_store
node_timetable_service -->|"loads school config"| node_shared_core
node_registrar -->|"publishes schedule"| node_timetable_service
node_shared_core -->|"defines timetable rules"| node_grid_rules
node_shared_core -.->|"builds solver input"| node_solver_input
node_solver_input -.->|"provides constraints"| node_solver_engine
node_solver_input -.->|"provides model data"| node_solver_v2
node_registrar -->|"generates timetable"| node_solver_engine
node_registrar -.->|"generates timetable"| node_solver_v2
node_teacher -->|"marks attendance"| node_daily_ui
node_daily_ui -.->|"requests operations"| node_api_client
node_http_server -->|"routes attendance"| node_attendance
node_http_server -->|"routes daily cover"| node_leave_cover
node_teacher -->|"requests leave"| node_leave_cover
node_http_server -->|"authenticates requests"| node_auth_gate
node_auth_gate -->|"resolves session"| node_auth_service
node_auth_service -->|"reads and writes"| node_db
node_registrar -.->|"administers accounts"| node_admin_ui
node_auth_service -->|"records events"| node_audit
node_timetable_service -->|"records changes"| node_audit

click node_app_entry "https://github.com/imatomic7407/timetable-studio/blob/main/app/src/App.tsx"
click node_store "https://github.com/imatomic7407/timetable-studio/blob/main/app/src/store/store.tsx"
click node_editor "https://github.com/imatomic7407/timetable-studio/blob/main/app/src/features/editor/EditorPage.tsx"
click node_rules_ui "https://github.com/imatomic7407/timetable-studio/blob/main/app/src/features/rules/RulesPage.tsx"
click node_teacher_portal "https://github.com/imatomic7407/timetable-studio/blob/main/app/src/features/teacherApp/TeacherApp.tsx"
click node_api_client "https://github.com/imatomic7407/timetable-studio/blob/main/app/src/data/api/apiClient.ts"
click node_http_server "https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/http/server.ts"
click node_timetable_routes "https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/http/routes/timetables.ts"
click node_timetable_service "https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/timetables/service.ts"
click node_timetable_store "https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/timetables/repository.ts"
click node_shared_core "https://github.com/imatomic7407/timetable-studio/blob/main/shared/timetable-core/src/types.ts"
click node_grid_rules "https://github.com/imatomic7407/timetable-studio/blob/main/shared/timetable-core/src/grid.ts"
click node_solver_input "https://github.com/imatomic7407/timetable-studio/blob/main/shared/timetable-core/src/solverInput.ts"
click node_solver_engine "https://github.com/imatomic7407/timetable-studio/blob/main/solver/solver/engine.py"
click node_solver_v2 "https://github.com/imatomic7407/timetable-studio/blob/main/solver/solver/v2/build.py"
click node_attendance "https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/attendance.ts"
click node_leave_cover "https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/cover.ts"
click node_daily_ui "https://github.com/imatomic7407/timetable-studio/blob/main/app/src/features/ops/AttendancePage.tsx"
click node_auth_service "https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/auth.ts"
click node_auth_gate "https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/http/middleware/auth.ts"
click node_audit "https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/audit.ts"
click node_db "https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/db/client.ts"
click node_admin_ui "https://github.com/imatomic7407/timetable-studio/blob/main/app/src/features/admin/UsersPage.tsx"

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_app_entry,node_store,node_editor,node_rules_ui,node_teacher_portal,node_api_client,node_admin_ui toneBlue
class node_http_server,node_timetable_routes,node_timetable_service,node_timetable_store toneAmber
class node_shared_core,node_grid_rules,node_solver_input,node_solver_engine,node_solver_v2 toneMint
class node_attendance,node_leave_cover,node_daily_ui toneRose
class node_auth_service,node_auth_gate,node_audit,node_db,node_registrar,node_teacher toneIndigo
```

## Components

### Web app

- [App entry](https://github.com/imatomic7407/timetable-studio/blob/main/app/src/App.tsx): `app/src/App.tsx`
- [App state](https://github.com/imatomic7407/timetable-studio/blob/main/app/src/store/store.tsx): `app/src/store/store.tsx`
- [Timetable editor](https://github.com/imatomic7407/timetable-studio/blob/main/app/src/features/editor/EditorPage.tsx): `app/src/features/editor/EditorPage.tsx`
- [Rule manager](https://github.com/imatomic7407/timetable-studio/blob/main/app/src/features/rules/RulesPage.tsx): `app/src/features/rules/RulesPage.tsx`
- [Teacher portal](https://github.com/imatomic7407/timetable-studio/blob/main/app/src/features/teacherApp/TeacherApp.tsx): `app/src/features/teacherApp/TeacherApp.tsx`
- [API client](https://github.com/imatomic7407/timetable-studio/blob/main/app/src/data/api/apiClient.ts): `app/src/data/api/apiClient.ts`
- [Administration](https://github.com/imatomic7407/timetable-studio/blob/main/app/src/features/admin/UsersPage.tsx): `app/src/features/admin/UsersPage.tsx`

### API and services

- [HTTP server](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/http/server.ts): `backend/src/http/server.ts`
- [Timetable routes](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/http/routes/timetables.ts): `backend/src/http/routes/timetables.ts`
- [Timetable lifecycle](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/timetables/service.ts): `backend/src/services/timetables/service.ts`
- [Timetable persistence](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/timetables/repository.ts): `backend/src/services/timetables/repository.ts`

### Timetable engine

- [Shared timetable model](https://github.com/imatomic7407/timetable-studio/blob/main/shared/timetable-core/src/types.ts): `shared/timetable-core/src/types.ts`
- [Grid and rule checks](https://github.com/imatomic7407/timetable-studio/blob/main/shared/timetable-core/src/grid.ts): `shared/timetable-core/src/grid.ts`
- [Solver input](https://github.com/imatomic7407/timetable-studio/blob/main/shared/timetable-core/src/solverInput.ts): `shared/timetable-core/src/solverInput.ts`
- [Schedule solver](https://github.com/imatomic7407/timetable-studio/blob/main/solver/solver/engine.py): `solver/solver/engine.py`
- [Solver v2](https://github.com/imatomic7407/timetable-studio/blob/main/solver/solver/v2/build.py): `solver/solver/v2/build.py`

### Daily operations

- [QR attendance](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/attendance.ts): `backend/src/services/attendance.ts`
- [Leave and cover](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/cover.ts): `backend/src/services/cover.ts`
- [Daily operations UI](https://github.com/imatomic7407/timetable-studio/blob/main/app/src/features/ops/AttendancePage.tsx): `app/src/features/ops/AttendancePage.tsx`

### Access and administration

- [Authentication](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/auth.ts): `backend/src/services/auth.ts`
- [Permission gates](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/http/middleware/auth.ts): `backend/src/http/middleware/auth.ts`
- [Audit trail](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/services/audit.ts): `backend/src/services/audit.ts`
- [Application database](https://github.com/imatomic7407/timetable-studio/blob/main/backend/src/db/client.ts): `backend/src/db/client.ts`

### Other components

- **Registrar**
- **Teacher**

## Connections

- Registrar → App entry: uses (evidence: `README.md`)
- Teacher → App entry: uses (evidence: `README.md`)
- App entry → App state: reads state (evidence: `app/src/App.tsx`)
- App entry → Teacher portal: routes teachers (evidence: `app/src/App.tsx`)
- Registrar → Timetable editor: edits schedule (evidence: `README.md`)
- Registrar → Rule manager: manages rules (evidence: `README.md`)
- Teacher → Teacher portal: views week (evidence: `README.md`)
- Timetable editor → API client: requests data
- Rule manager → API client: requests rules
- Teacher portal → API client: requests data
- API client → HTTP server: sends requests (evidence: `README.md`)
- HTTP server → Timetable routes: mounts routes (evidence: `backend/src/http/server.ts`)
- Timetable routes → Timetable lifecycle: dispatches
- Timetable lifecycle → Timetable persistence: maps records (evidence: `backend/src/services/timetables/service.ts`)
- Timetable lifecycle → Shared timetable model: loads school config (evidence: `backend/src/services/timetables/service.ts`)
- Registrar → Timetable lifecycle: publishes schedule (evidence: `README.md`)
- Shared timetable model → Grid and rule checks: defines timetable rules (evidence: `shared/timetable-core/src/rules.ts`)
- Shared timetable model → Solver input: builds solver input
- Solver input → Schedule solver: provides constraints
- Solver input → Solver v2: provides model data
- Registrar → Schedule solver: generates timetable (evidence: `README.md`)
- Registrar → Solver v2: generates timetable
- Teacher → Daily operations UI: marks attendance (evidence: `README.md`)
- Daily operations UI → API client: requests operations
- HTTP server → QR attendance: routes attendance (evidence: `backend/src/http/server.ts`)
- HTTP server → Leave and cover: routes daily cover (evidence: `backend/src/http/server.ts`)
- Teacher → Leave and cover: requests leave (evidence: `README.md`)
- HTTP server → Permission gates: authenticates requests (evidence: `backend/src/http/server.ts`)
- Permission gates → Authentication: resolves session (evidence: `backend/src/http/middleware/auth.ts`)
- Authentication → Application database: reads and writes (evidence: `backend/src/services/auth.ts`)
- Registrar → Administration: administers accounts
- Authentication → Audit trail: records events (evidence: `backend/src/services/auth.ts`)
- Timetable lifecycle → Audit trail: records changes (evidence: `backend/src/services/timetables/service.ts`)
