# athulnath03/automatic-timetable-and-schedule-generator architecture

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

- Interactive diagram: https://gitdiagram.com/athulnath03/automatic-timetable-and-schedule-generator
- Repository: https://github.com/athulnath03/automatic-timetable-and-schedule-generator

## Overview

This is a **small full-stack web application**:

- **Frontend:** React (Vite) “dashboard” UI (`frontend/`)
- **Backend:** Flask API + static file hosting (`backend/app.py`)
- **Core domain logic:** a **timetable generator** (greedy scheduler) in `backend/scheduler.py`
- **Primary user flow:** user configures timetable inputs in the UI → UI calls Flask `/api/generate` → backend runs scheduler → returns generated timetable → UI renders and optionally saves/displays it.

- **Two-tier app** (browser UI + API server)
- **API contract** (`/api/health`, `/api/generate`)
- **Runtime modes**: dev mode (Vite + Flask separate) vs prod mode (Flask serves built static assets)
- **Internal backend decomposition**: routing layer vs scheduler module

##### Generate flow
- User enters:
- days, periods_per_day, classes, subjects[{name, teacher, periods_per_week}]
- Frontend sends JSON → `POST /api/generate`
- Backend validates/parses JSON → calls `scheduler.py`
- Scheduler returns “timetable structure” → Flask returns JSON
- Frontend renders result in `TimetableView`

##### Health flow
- Frontend/dev tools/curl → `GET /api/health` → simple JSON status

##### Static asset flow (prod)
- Browser GET `/` and `/assets/*` → Flask serves from `frontend/dist`

- [ ] Shows React+Vite frontend and Flask backend as separate deployable/run components
- [ ] Shows `/api/generate` calling `backend/scheduler.py`
- [ ] Shows dev ports (5173 and 5000) and CORS note
- [ ] Shows prod static hosting from `frontend/dist` by Flask
- [ ] Does **not** show a DB unless you confirm one exists

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================================================
%% External Actor
%% =========================================================
U["User (Teacher/Admin)\nBrowser"]:::external

%% =========================================================
%% Development Runtime (2-process)
%% =========================================================
subgraph "Development Mode (two origins)"
direction TB

DEV_BROWSER["Browser Session\n(Dev)"]:::external

subgraph "Frontend Dev Server"
direction TB
VITE["Vite Dev Server\nServes React SPA\nlocalhost:5173"]:::runtime
SPA_DEV["React SPA (Dev)\nUI + Client State"]:::frontend
end

subgraph "Backend API Server"
direction TB
FLASK_DEV["Flask API Server (Dev)\nCORS enabled\n127.0.0.1:5000"]:::runtime
API_ROUTES_DEV["API Routes\nGET /api/health\nPOST /api/generate"]:::api
SCHED_DEV["Timetable Generator\nGreedy Scheduler"]:::domain
end

DEV_NOTE["Dev Routing\n5173 → 5000 (CORS)\nJSON over HTTP"]:::note
end

%% =========================================================
%% Production Runtime (1-process, same origin)
%% =========================================================
subgraph "Production Mode (single origin)"
direction TB

PROD_BROWSER["Browser Session\n(Prod)"]:::external

subgraph "Flask Server (Serves SPA + API)"
direction TB
FLASK_PROD["Flask App Server (Prod)\nSingle Origin :5000"]:::runtime
STATIC_SERVE["Static Hosting\nServes built assets"]:::artifact
DIST["Built Frontend Assets\n(frontend/dist)"]:::artifact
API_ROUTES_PROD["API Routes\nGET /api/health\nPOST /api/generate"]:::api
SCHED_PROD["Timetable Generator\nGreedy Scheduler"]:::domain
end

PROD_NOTE["Prod Routing\n/: serves SPA\n/api/*: serves JSON\nSame origin"]:::note
end

%% =========================================================
%% Frontend Component / Page Flow (logical UI mapping)
%% =========================================================
subgraph "Frontend UI Composition (React)"
direction TB
APP["App Layout + Navigation"]:::frontend
TOPBAR["Topbar"]:::frontend
SIDEBAR["Sidebar"]:::frontend
HOME["DashboardHome"]:::frontend

GEN["GeneratePage\nCollect inputs:\n- days, periods\n- classes\n- subjects[{name,teacher,periods_per_week}]"]:::frontend
VIEW["TimetableView\nRender generated timetable"]:::frontend
SAVED["SavedPage\nSaved timetables (client-side)"]:::frontend

STATE["React State\n(In-memory)"]:::state
BSTORE[("Browser Storage\n(LocalStorage?)")]:::optional
end

%% =========================================================
%% Shared Backend Internal Decomposition (source modules)
%% =========================================================
subgraph "Backend Modules (Source)"
direction TB
APP_PY["app.py\nTransport layer:\n- Routes\n- CORS (dev)\n- Static serve (prod)"]:::backend
SCHED_PY["scheduler.py\nDomain logic:\nGreedy timetable generator"]:::domain
REQS["requirements.txt\nBackend dependencies"]:::artifact
end

%% =========================================================
%% Primary User Flows / Connections
%% =========================================================

U -->|"uses"| DEV_BROWSER
U -->|"uses"| PROD_BROWSER

%% Dev: serve SPA + call API
DEV_BROWSER -->|"HTTP GET / (SPA)\n:5173"| VITE
VITE -->|"serves HTML/JS/CSS"| SPA_DEV

SPA_DEV -->|"renders"| APP
APP -->|"layout"| TOPBAR
APP -->|"layout"| SIDEBAR
APP -->|"routes"| HOME
APP -->|"routes"| GEN
APP -->|"routes"| SAVED
GEN -->|"updates"| STATE
STATE -->|"drives UI"| VIEW

GEN -->|"fetch(JSON)\nPOST /api/generate\n5173 → 5000"| API_ROUTES_DEV
API_ROUTES_DEV -->|"calls generate() with parsed JSON"| SCHED_DEV
SCHED_DEV -->|"returns timetable structure"| API_ROUTES_DEV
API_ROUTES_DEV -->|"HTTP 200 JSON\n{timetable: ...}"| GEN
GEN -->|"stores result"| STATE

DEV_BROWSER -->|"HTTP GET\n/api/health"| API_ROUTES_DEV
DEV_NOTE --- VITE
DEV_NOTE --- FLASK_DEV

%% Dev backend wiring to source modules
FLASK_DEV -->|"implemented in"| APP_PY
API_ROUTES_DEV -->|"defined in"| APP_PY
SCHED_DEV -->|"implemented in"| SCHED_PY
APP_PY -->|"imports/calls"| SCHED_PY
APP_PY -->|"uses deps"| REQS

%% Prod: Flask serves SPA + API on same origin
PROD_BROWSER -->|"HTTP GET / and /assets/*\n:5000"| STATIC_SERVE
STATIC_SERVE -->|"serves"| DIST
DIST -->|"loads SPA"| APP

PROD_BROWSER -->|"HTTP JSON\nPOST /api/generate"| API_ROUTES_PROD
API_ROUTES_PROD -->|"calls scheduler"| SCHED_PROD
SCHED_PROD -->|"returns timetable structure"| API_ROUTES_PROD

PROD_BROWSER -->|"HTTP GET\n/api/health"| API_ROUTES_PROD
PROD_NOTE --- FLASK_PROD
FLASK_PROD -->|"serves static from"| DIST
FLASK_PROD -->|"implemented in"| APP_PY
API_ROUTES_PROD -->|"defined in"| APP_PY
SCHED_PROD -->|"implemented in"| SCHED_PY

%% Saved feature (assumption only)
SAVED -->|"read/write (if implemented)"| BSTORE
BSTORE -.->|"optional\nnot verified"| SAVED

%% =========================================================
%% Click Events (from component_mapping)
%% =========================================================
click APP_PY "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/backend/app.py"
click SCHED_PY "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/backend/scheduler.py"
click REQS "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/backend/requirements.txt"

click SPA_DEV "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/tree/main/frontend/"
click VITE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/vite.config.js"
click DIST "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/tree/main/frontend/"
click APP "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/src/App.jsx"
click TOPBAR "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/src/components/Topbar.jsx"
click SIDEBAR "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/src/components/Sidebar.jsx"
click HOME "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/src/components/DashboardHome.jsx"
click GEN "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/src/components/GeneratePage.jsx"
click VIEW "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/src/components/TimetableView.jsx"
click SAVED "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/src/components/SavedPage.jsx"
click STATE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/src/main.jsx"

click STATIC_SERVE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/index.html"
click DEV_NOTE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/README.md"
click PROD_NOTE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/README.md"

%% Additional mapped files
click BSTORE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/tree/main/frontend/src/components/"
click API_ROUTES_DEV "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/backend/app.py"
click API_ROUTES_PROD "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/backend/app.py"
click FLASK_DEV "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/backend/app.py"
click FLASK_PROD "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/backend/app.py"

%% Optional artifacts mentioned
click DEV_BROWSER "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/tree/main/timetable"
click PROD_BROWSER "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/tree/main/stop_timetable"

%% Frontend project files
click SPA_DEV "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/tree/main/frontend/"
click STATIC_SERVE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/index.html"
click VITE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/vite.config.js"
click STATE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/src/main.jsx"

%% package metadata
click DEV_NOTE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/package.json"
click PROD_NOTE "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/package-lock.json"

%% styles
click VIEW "https://github.com/athulnath03/automatic-timetable-and-schedule-generator/blob/main/frontend/src/styles.css"

%% =========================================================
%% Styles
%% =========================================================
classDef external fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1px
classDef runtime fill:#fff7ed,stroke:#c2410c,color:#111827,stroke-width:2px
classDef frontend fill:#dbeafe,stroke:#1d4ed8,color:#0b1220,stroke-width:1px
classDef backend fill:#dcfce7,stroke:#15803d,color:#0b1220,stroke-width:1px
classDef api fill:#bbf7d0,stroke:#166534,color:#0b1220,stroke-width:1px
classDef domain fill:#a7f3d0,stroke:#047857,color:#0b1220,stroke-width:1px
classDef artifact fill:#f3e8ff,stroke:#7e22ce,color:#0b1220,stroke-width:1px
classDef state fill:#cffafe,stroke:#0891b2,color:#0b1220,stroke-width:1px
classDef optional fill:#ffffff,stroke:#6b7280,color:#111827,stroke-width:1px,stroke-dasharray: 5 5
classDef note fill:#fef9c3,stroke:#a16207,color:#111827,stroke-width:1px,stroke-dasharray: 3 3
```
