# hengdapi/school-timetable-generator architecture

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

- Interactive diagram: https://gitdiagram.com/hengdapi/school-timetable-generator
- Repository: https://github.com/hengdapi/school-timetable-generator

## Overview

School Timetable Generator is a desktop tool for configuring school scheduling inputs and constraints, automatically generating timetables, manually correcting them, and exporting class/teacher schedules or CSES files. The graph follows the documented product workflow and the visible startup and generation excerpts. Several settings, import, editing, and export connections are documented in the README but their implementation was not sampled, so those links are represented only where the tree and module names support them.

Main entry points: [`pages/generate.py`](https://github.com/hengdapi/school-timetable-generator/blob/master/pages/generate.py) (Generation page), [`core/generate_core.py`](https://github.com/hengdapi/school-timetable-generator/blob/master/core/generate_core.py) (Constraint scheduler), [`main.py`](https://github.com/hengdapi/school-timetable-generator/blob/master/main.py) (Application shell), [`pages/settings.py`](https://github.com/hengdapi/school-timetable-generator/blob/master/pages/settings.py) (Settings page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_app["Application shell<br/>[main.py]"]
  node_home["Home page<br/>[home.py]"]
  node_settings_ui["Settings page<br/>[settings.py]"]
  node_generate_ui["Generation page<br/>[generate.py]"]
  node_timeline["Timeline view<br/>[timeline.py]"]
  node_dialogs["Dialogs<br/>[dialogs.py]"]
end

subgraph group_input["Scheduling inputs"]
  node_settings[("Settings state<br/>[wr_settings.py]")]
  node_school_data["School data<br/>[locals.py]"]
  node_rules["Scheduling rules<br/>[rules.py]"]
end

subgraph group_generation["Timetable generation"]
  node_generator["Constraint scheduler<br/>[generate_core.py]"]
  node_timetable[("Timetable state<br/>[locals.py]")]
end

subgraph group_output["Review and export"]
  node_manual_edit["Manual adjustment<br/>[generate.py]"]
  node_save_plan["Plan persistence<br/>[save_core.py]"]
  node_schedule_export["Schedule export<br/>[save_core.py]"]
  node_cses_export["CSES export<br/>[cses_core.py]"]
  node_notifications["Completion alerts"]
end

node_user(("School staff"))
node_spreadsheet["Spreadsheet files"]
node_cses_files["CSES YAML files"]

node_user -->|"launches"| node_app
node_app -->|"opens"| node_home
node_app -->|"opens"| node_settings_ui
node_app -->|"opens"| node_generate_ui
node_settings_ui -->|"configures"| node_settings
node_settings_ui -->|"imports inputs"| node_school_data
node_settings_ui -->|"configures"| node_rules
node_generate_ui -->|"starts generation"| node_generator
node_generator -->|"checks constraints"| node_rules
node_generator -->|"reads classes"| node_school_data
node_generator -->|"reads options"| node_settings
node_generator -->|"assigns lessons"| node_timetable
node_generate_ui -->|"edits schedule"| node_manual_edit
node_manual_edit -->|"updates lessons"| node_timetable
node_generate_ui -->|"shows schedule"| node_timeline
node_generate_ui -->|"manages plans"| node_save_plan
node_generate_ui -->|"exports schedules"| node_schedule_export
node_generate_ui -->|"exports CSES"| node_cses_export
node_schedule_export -->|"writes files"| node_spreadsheet
node_cses_export -->|"writes YAML"| node_cses_files
node_generate_ui -->|"requests alerts"| node_notifications

click node_app "https://github.com/hengdapi/school-timetable-generator/blob/master/main.py"
click node_home "https://github.com/hengdapi/school-timetable-generator/blob/master/pages/home.py"
click node_settings_ui "https://github.com/hengdapi/school-timetable-generator/blob/master/pages/settings.py"
click node_generate_ui "https://github.com/hengdapi/school-timetable-generator/blob/master/pages/generate.py"
click node_timeline "https://github.com/hengdapi/school-timetable-generator/blob/master/pages/timeline.py"
click node_dialogs "https://github.com/hengdapi/school-timetable-generator/blob/master/pages/dialogs.py"
click node_settings "https://github.com/hengdapi/school-timetable-generator/blob/master/wr_settings.py"
click node_school_data "https://github.com/hengdapi/school-timetable-generator/blob/master/locals.py"
click node_rules "https://github.com/hengdapi/school-timetable-generator/blob/master/core/rules.py"
click node_generator "https://github.com/hengdapi/school-timetable-generator/blob/master/core/generate_core.py"
click node_timetable "https://github.com/hengdapi/school-timetable-generator/blob/master/locals.py"
click node_manual_edit "https://github.com/hengdapi/school-timetable-generator/blob/master/pages/generate.py"
click node_save_plan "https://github.com/hengdapi/school-timetable-generator/blob/master/core/save_core.py"
click node_schedule_export "https://github.com/hengdapi/school-timetable-generator/blob/master/core/save_core.py"
click node_cses_export "https://github.com/hengdapi/school-timetable-generator/blob/master/core/cses_core.py"
click node_notifications "https://github.com/hengdapi/school-timetable-generator/blob/master/core/system_notification.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_home,node_settings_ui,node_generate_ui,node_timeline,node_dialogs toneBlue
class node_settings,node_school_data,node_rules toneAmber
class node_generator,node_timetable toneMint
class node_manual_edit,node_save_plan,node_schedule_export,node_cses_export,node_notifications toneRose
class node_user,node_spreadsheet,node_cses_files toneIndigo
```

## Components

### Desktop interface

- [Application shell](https://github.com/hengdapi/school-timetable-generator/blob/master/main.py): `main.py`
- [Home page](https://github.com/hengdapi/school-timetable-generator/blob/master/pages/home.py): `pages/home.py`
- [Settings page](https://github.com/hengdapi/school-timetable-generator/blob/master/pages/settings.py): `pages/settings.py`
- [Generation page](https://github.com/hengdapi/school-timetable-generator/blob/master/pages/generate.py): `pages/generate.py`
- [Timeline view](https://github.com/hengdapi/school-timetable-generator/blob/master/pages/timeline.py): `pages/timeline.py`
- [Dialogs](https://github.com/hengdapi/school-timetable-generator/blob/master/pages/dialogs.py): `pages/dialogs.py`

### Scheduling inputs

- [Settings state](https://github.com/hengdapi/school-timetable-generator/blob/master/wr_settings.py): `wr_settings.py`
- [School data](https://github.com/hengdapi/school-timetable-generator/blob/master/locals.py): `locals.py`
- [Scheduling rules](https://github.com/hengdapi/school-timetable-generator/blob/master/core/rules.py): `core/rules.py`

### Timetable generation

- [Constraint scheduler](https://github.com/hengdapi/school-timetable-generator/blob/master/core/generate_core.py): `core/generate_core.py`
- [Timetable state](https://github.com/hengdapi/school-timetable-generator/blob/master/locals.py): `locals.py`

### Review and export

- [Manual adjustment](https://github.com/hengdapi/school-timetable-generator/blob/master/pages/generate.py): `pages/generate.py`
- [Plan persistence](https://github.com/hengdapi/school-timetable-generator/blob/master/core/save_core.py): `core/save_core.py`
- [Schedule export](https://github.com/hengdapi/school-timetable-generator/blob/master/core/save_core.py): `core/save_core.py`
- [CSES export](https://github.com/hengdapi/school-timetable-generator/blob/master/core/cses_core.py): `core/cses_core.py`
- [Completion alerts](https://github.com/hengdapi/school-timetable-generator/blob/master/core/system_notification.py): `core/system_notification.py`

### Other components

- **School staff**
- **Spreadsheet files**
- **CSES YAML files**

## Connections

- School staff → Application shell: launches
- Application shell → Home page: opens
- Application shell → Settings page: opens
- Application shell → Generation page: opens
- Settings page → Settings state: configures
- Settings page → School data: imports inputs
- Settings page → Scheduling rules: configures
- Generation page → Constraint scheduler: starts generation
- Constraint scheduler → Scheduling rules: checks constraints
- Constraint scheduler → School data: reads classes
- Constraint scheduler → Settings state: reads options
- Constraint scheduler → Timetable state: assigns lessons
- Generation page → Manual adjustment: edits schedule
- Manual adjustment → Timetable state: updates lessons
- Generation page → Timeline view: shows schedule
- Generation page → Plan persistence: manages plans
- Generation page → Schedule export: exports schedules
- Generation page → CSES export: exports CSES
- Schedule export → Spreadsheet files: writes files
- CSES export → CSES YAML files: writes YAML
- Generation page → Completion alerts: requests alerts