How ankitsencode123/timetable-application works
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: api.ts HTTP API client · router.py API router · database.py SQL database · timetable_service.py Timetable service
Components 29
Web client
- Application routes
frontend/src/App.tsx - Schedule workspace
frontend/src/pages/TeacherWorkspace.tsx - Calendar management
frontend/src/components/calendar/CalendarManager.tsx - Busy slots
frontend/src/components/busyslots/BusySlotsManager.tsx - Catalog management
frontend/src/components/catalog/CatalogManager.tsx - Chat assistant
frontend/src/components/chat/ChatPanel.tsx - Client state
frontend/src/store.ts - HTTP API client
frontend/src/api.ts
API and identity
- API router
backend/app/api/router.py - Authentication routes
backend/app/api/auth.py - Schedule routes
backend/app/api/timetable.py - Smart scheduling routes
backend/app/api/schedule_smart.py - Action routes
backend/app/api/actions.py - Chat routes
backend/app/api/chat.py - Identity service
backend/app/services/auth_service.py
Scheduling domain
- Action orchestration
backend/app/actions/engine.py - Chat processing
backend/app/services/chat_service.py - Intent parser
backend/app/actions/parser.py - Scheduling service
backend/app/services/scheduler_service.py - Schedule suggestions
backend/app/actions/suggestions.py - Fast suggester
backend/app/scheduler/fast_suggester.py - Constraint validator
backend/app/scheduler/validator.py - Scheduling constraints
backend/app/scheduler/constraints.py
Timetable data
- Timetable service
backend/app/services/timetable_service.py - Timetable versions
backend/app/models/timetable.py - Timetable entries
backend/app/models/timetable_entry.py - User records
backend/app/models/user.py - SQL database
backend/app/core/database.py
Other components
- Teacher or admin
Connections 33
- Teacher or admin → Application routes: uses
- Application routes → Schedule workspace: routes to
frontend/src/App.tsx - Schedule workspace → HTTP API client: requests data
- Calendar management → HTTP API client: requests data
frontend/src/components/calendar/CalendarManager.tsx - Busy slots → HTTP API client: requests data
frontend/src/components/busyslots/BusySlotsManager.tsx - Catalog management → HTTP API client: requests data
frontend/src/components/catalog/CatalogManager.tsx - Chat assistant → HTTP API client: sends prompts
- Client state → HTTP API client: uses
frontend/src/store.ts - HTTP API client → API router: calls REST API
- API router → Authentication routes: registers
backend/app/api/router.py - API router → Schedule routes: registers
backend/app/api/router.py - API router → Smart scheduling routes: registers
backend/app/api/router.py - API router → Action routes: registers
backend/app/api/router.py - API router → Chat routes: registers
backend/app/api/router.py - Authentication routes → Identity service: delegates
- Action orchestration → Constraint validator: validates changes
backend/app/actions/engine.py - Action orchestration → Timetable service: persists draft
backend/app/actions/engine.py - Action orchestration → Schedule suggestions: requests alternatives
backend/app/actions/engine.py - Chat processing → Intent parser: parses requests
backend/app/services/chat_service.py - Chat processing → Scheduling constraints: uses schedule rules
backend/app/services/chat_service.py - Scheduling service → Fast suggester: uses suggestions
- Schedule suggestions → Fast suggester: uses
backend/app/actions/suggestions.py - Schedule suggestions → Constraint validator: checks candidates
backend/app/actions/suggestions.py - Constraint validator → Scheduling constraints: applies rules
backend/app/scheduler/validator.py - Scheduling constraints → SQL database: reloads catalog
backend/app/scheduler/constraints.py - Timetable service → Fast suggester: uses
backend/app/services/timetable_service.py - Timetable service → Timetable versions: reads and writes
backend/app/services/timetable_service.py - Timetable service → Timetable entries: reads and writes
backend/app/services/timetable_service.py - Identity service → User records: manages users
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