# ankitsencode123/timetable-application architecture

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

- Interactive diagram: https://gitdiagram.com/ankitsencode123/timetable-application
- Repository: https://github.com/ankitsencode123/timetable-application

## Overview

Timely is a timetable-management product with a React client and FastAPI backend. The main workflow is users viewing or editing schedules, submitting changes through the API, and having the backend validate and version the resulting timetable; smart rescheduling and an AI chat assistant are additional scheduling paths. The README documents PostgreSQL-backed storage and major capabilities. Some endpoint-to-service and persistence details are unsampled, so those relationships are omitted rather than inferred.

Main entry points: [`frontend/src/api.ts`](https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/api.ts) (HTTP API client), [`backend/app/api/router.py`](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/router.py) (API router), [`backend/app/core/database.py`](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/core/database.py) (SQL database), [`backend/app/services/timetable_service.py`](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/services/timetable_service.py) (Timetable service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Application routes<br/>[App.tsx]"]
  node_workspace["Schedule workspace"]
  node_calendar_ui["Calendar management"]
  node_busy_ui["Busy slots"]
  node_catalog_ui["Catalog management<br/>[CatalogManager.tsx]"]
  node_chat_ui["Chat assistant<br/>[ChatPanel.tsx]"]
  node_client_state["Client state<br/>[store.ts]"]
  node_client_api["HTTP API client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_api_router["API router<br/>[router.py]"]
  node_auth_api["Authentication routes<br/>[auth.py]"]
  node_schedule_api["Schedule routes<br/>[timetable.py]"]
  node_smart_api["Smart scheduling routes<br/>[schedule_smart.py]"]
  node_actions_api["Action routes<br/>[actions.py]"]
  node_chat_api["Chat routes<br/>[chat.py]"]
  node_auth_service["Identity service<br/>[auth_service.py]"]
end

subgraph group_schedule["Scheduling domain"]
  node_action_engine["Action orchestration<br/>[engine.py]"]
  node_chat_service["Chat processing<br/>[chat_service.py]"]
  node_action_parser["Intent parser<br/>[parser.py]"]
  node_scheduler_service["Scheduling service"]
  node_suggestions["Schedule suggestions<br/>[suggestions.py]"]
  node_fast_suggester["Fast suggester<br/>[fast_suggester.py]"]
  node_validator["Constraint validator<br/>[validator.py]"]
  node_constraints["Scheduling constraints<br/>[constraints.py]"]
end

subgraph group_data["Timetable data"]
  node_timetable_service["Timetable service"]
  node_version_model[("Timetable versions<br/>[timetable.py]")]
  node_entry_model[("Timetable entries<br/>[timetable_entry.py]")]
  node_user_model[("User records<br/>[user.py]")]
  node_database[("SQL database<br/>[database.py]")]
end

node_user(("Teacher or admin"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_workspace
node_workspace -.->|"requests data"| node_client_api
node_calendar_ui -->|"requests data"| node_client_api
node_busy_ui -->|"requests data"| node_client_api
node_catalog_ui -->|"requests data"| node_client_api
node_chat_ui -.->|"sends prompts"| node_client_api
node_client_state -->|"uses"| node_client_api
node_client_api -->|"calls REST API"| node_api_router
node_api_router -->|"registers"| node_auth_api
node_api_router -->|"registers"| node_schedule_api
node_api_router -->|"registers"| node_smart_api
node_api_router -->|"registers"| node_actions_api
node_api_router -->|"registers"| node_chat_api
node_auth_api -.->|"delegates"| node_auth_service
node_action_engine -->|"validates changes"| node_validator
node_action_engine -->|"persists draft"| node_timetable_service
node_action_engine -->|"requests alternatives"| node_suggestions
node_chat_service -->|"parses requests"| node_action_parser
node_chat_service -->|"uses schedule rules"| node_constraints
node_scheduler_service -.->|"uses suggestions"| node_fast_suggester
node_suggestions -->|"uses"| node_fast_suggester
node_suggestions -->|"checks candidates"| node_validator
node_validator -->|"applies rules"| node_constraints
node_constraints -->|"reloads catalog"| node_database
node_timetable_service -->|"uses"| node_fast_suggester
node_timetable_service -->|"reads and writes"| node_version_model
node_timetable_service -->|"reads and writes"| node_entry_model
node_auth_service -->|"manages users"| node_user_model
node_auth_service -.->|"queries records"| node_database
node_version_model -.->|"stored in"| node_database
node_entry_model -.->|"stored in"| node_database
node_user_model -.->|"stored in"| node_database

click node_app "https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/App.tsx"
click node_workspace "https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/pages/TeacherWorkspace.tsx"
click node_calendar_ui "https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/components/calendar/CalendarManager.tsx"
click node_busy_ui "https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/components/busyslots/BusySlotsManager.tsx"
click node_catalog_ui "https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/components/catalog/CatalogManager.tsx"
click node_chat_ui "https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/components/chat/ChatPanel.tsx"
click node_client_state "https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/store.ts"
click node_client_api "https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/api.ts"
click node_api_router "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/router.py"
click node_auth_api "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/auth.py"
click node_schedule_api "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/timetable.py"
click node_smart_api "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/schedule_smart.py"
click node_actions_api "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/actions.py"
click node_chat_api "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/chat.py"
click node_auth_service "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/services/auth_service.py"
click node_action_engine "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/actions/engine.py"
click node_chat_service "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/services/chat_service.py"
click node_action_parser "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/actions/parser.py"
click node_scheduler_service "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/services/scheduler_service.py"
click node_suggestions "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/actions/suggestions.py"
click node_fast_suggester "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/scheduler/fast_suggester.py"
click node_validator "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/scheduler/validator.py"
click node_constraints "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/scheduler/constraints.py"
click node_timetable_service "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/services/timetable_service.py"
click node_version_model "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/models/timetable.py"
click node_entry_model "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/models/timetable_entry.py"
click node_user_model "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/models/user.py"
click node_database "https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/core/database.py"

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,node_workspace,node_calendar_ui,node_busy_ui,node_catalog_ui,node_chat_ui,node_client_state,node_client_api toneBlue
class node_api_router,node_auth_api,node_schedule_api,node_smart_api,node_actions_api,node_chat_api,node_auth_service toneAmber
class node_action_engine,node_chat_service,node_action_parser,node_scheduler_service,node_suggestions,node_fast_suggester,node_validator,node_constraints toneMint
class node_timetable_service,node_version_model,node_entry_model,node_user_model,node_database toneRose
class node_user toneIndigo
```

## Components

### Web client

- [Application routes](https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Schedule workspace](https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/pages/TeacherWorkspace.tsx): `frontend/src/pages/TeacherWorkspace.tsx`
- [Calendar management](https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/components/calendar/CalendarManager.tsx): `frontend/src/components/calendar/CalendarManager.tsx`
- [Busy slots](https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/components/busyslots/BusySlotsManager.tsx): `frontend/src/components/busyslots/BusySlotsManager.tsx`
- [Catalog management](https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/components/catalog/CatalogManager.tsx): `frontend/src/components/catalog/CatalogManager.tsx`
- [Chat assistant](https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/components/chat/ChatPanel.tsx): `frontend/src/components/chat/ChatPanel.tsx`
- [Client state](https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/store.ts): `frontend/src/store.ts`
- [HTTP API client](https://github.com/ankitsencode123/timetable-application/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### API and identity

- [API router](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Authentication routes](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Schedule routes](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/timetable.py): `backend/app/api/timetable.py`
- [Smart scheduling routes](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/schedule_smart.py): `backend/app/api/schedule_smart.py`
- [Action routes](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/actions.py): `backend/app/api/actions.py`
- [Chat routes](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Identity service](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`

### Scheduling domain

- [Action orchestration](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/actions/engine.py): `backend/app/actions/engine.py`
- [Chat processing](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/services/chat_service.py): `backend/app/services/chat_service.py`
- [Intent parser](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/actions/parser.py): `backend/app/actions/parser.py`
- [Scheduling service](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/services/scheduler_service.py): `backend/app/services/scheduler_service.py`
- [Schedule suggestions](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/actions/suggestions.py): `backend/app/actions/suggestions.py`
- [Fast suggester](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/scheduler/fast_suggester.py): `backend/app/scheduler/fast_suggester.py`
- [Constraint validator](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/scheduler/validator.py): `backend/app/scheduler/validator.py`
- [Scheduling constraints](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/scheduler/constraints.py): `backend/app/scheduler/constraints.py`

### Timetable data

- [Timetable service](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/services/timetable_service.py): `backend/app/services/timetable_service.py`
- [Timetable versions](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/models/timetable.py): `backend/app/models/timetable.py`
- [Timetable entries](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/models/timetable_entry.py): `backend/app/models/timetable_entry.py`
- [User records](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [SQL database](https://github.com/ankitsencode123/timetable-application/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Teacher or admin**

## Connections

- Teacher or admin → Application routes: uses
- Application routes → Schedule workspace: routes to (evidence: `frontend/src/App.tsx`)
- Schedule workspace → HTTP API client: requests data
- Calendar management → HTTP API client: requests data (evidence: `frontend/src/components/calendar/CalendarManager.tsx`)
- Busy slots → HTTP API client: requests data (evidence: `frontend/src/components/busyslots/BusySlotsManager.tsx`)
- Catalog management → HTTP API client: requests data (evidence: `frontend/src/components/catalog/CatalogManager.tsx`)
- Chat assistant → HTTP API client: sends prompts
- Client state → HTTP API client: uses (evidence: `frontend/src/store.ts`)
- HTTP API client → API router: calls REST API
- API router → Authentication routes: registers (evidence: `backend/app/api/router.py`)
- API router → Schedule routes: registers (evidence: `backend/app/api/router.py`)
- API router → Smart scheduling routes: registers (evidence: `backend/app/api/router.py`)
- API router → Action routes: registers (evidence: `backend/app/api/router.py`)
- API router → Chat routes: registers (evidence: `backend/app/api/router.py`)
- Authentication routes → Identity service: delegates
- Action orchestration → Constraint validator: validates changes (evidence: `backend/app/actions/engine.py`)
- Action orchestration → Timetable service: persists draft (evidence: `backend/app/actions/engine.py`)
- Action orchestration → Schedule suggestions: requests alternatives (evidence: `backend/app/actions/engine.py`)
- Chat processing → Intent parser: parses requests (evidence: `backend/app/services/chat_service.py`)
- Chat processing → Scheduling constraints: uses schedule rules (evidence: `backend/app/services/chat_service.py`)
- Scheduling service → Fast suggester: uses suggestions
- Schedule suggestions → Fast suggester: uses (evidence: `backend/app/actions/suggestions.py`)
- Schedule suggestions → Constraint validator: checks candidates (evidence: `backend/app/actions/suggestions.py`)
- Constraint validator → Scheduling constraints: applies rules (evidence: `backend/app/scheduler/validator.py`)
- Scheduling constraints → SQL database: reloads catalog (evidence: `backend/app/scheduler/constraints.py`)
- Timetable service → Fast suggester: uses (evidence: `backend/app/services/timetable_service.py`)
- Timetable service → Timetable versions: reads and writes (evidence: `backend/app/services/timetable_service.py`)
- Timetable service → Timetable entries: reads and writes (evidence: `backend/app/services/timetable_service.py`)
- Identity service → User records: manages users (evidence: `backend/app/services/auth_service.py`)
- Identity service → SQL database: queries records
- Timetable versions → SQL database: stored in
- Timetable entries → SQL database: stored in
- User records → SQL database: stored in
