# shutdown-awa/xiqueer2ics architecture

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

- Interactive diagram: https://gitdiagram.com/shutdown-awa/xiqueer2ics
- Repository: https://github.com/shutdown-awa/xiqueer2ics

## Overview

XiQueEr2ICS fetches a student’s timetable from a school’s academic system and turns it into an ICS calendar, either through a web subscription endpoint or a local script. The web flow validates the request, dispatches to the selected school adapter, uses cached timetable data when applicable, and builds calendar events using school-term dates and timetable settings. A separate documented workflow synchronizes public school-calendar data. Source excerpts are partial; unsampled web verification details and some cache wiring are represented only where supported by the README or visible entry points.

Main entry points: [`xqe.py`](https://github.com/shutdown-awa/xiqueer2ics/blob/main/xqe.py) (Timetable and ICS), [`schools/12623/main.py`](https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/main.py) (School timetable adapter), [`api.py`](https://github.com/shutdown-awa/xiqueer2ics/blob/main/api.py) (ICS API), [`web/scripts.js`](https://github.com/shutdown-awa/xiqueer2ics/blob/main/web/scripts.js) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web subscription"]
  node_browser["Browser UI<br/>[scripts.js]"]
  node_school_list["School list<br/>[schools.json]"]
  node_api["ICS API<br/>[api.py]"]
end

subgraph group_core["Timetable to ICS"]
  node_engine["Timetable and ICS<br/>[xqe.py]"]
  node_cache[("User timetable cache<br/>[xqe.py]")]
  node_ics["ICS calendar"]
end

subgraph group_school["School integration"]
  node_dispatcher["School dispatcher<br/>[xqe.py]"]
  node_adapter["School timetable adapter<br/>[main.py]"]
  node_des["Kingo DES<br/>[jkingo_des.py]"]
  node_school_config["School configuration<br/>[config.json]"]
  node_timetable_config["Timetable settings<br/>[timetable.json]"]
end

subgraph group_calendar["Calendar maintenance"]
  node_calendar_data["School calendar data"]
  node_sync["School calendar sync<br/>[maintain.py]"]
end

node_student(("Student"))
node_calendar_app(("Calendar app"))
node_cli(("Local script user"))
node_portal["Academic system"]
node_public_calendar["Public calendar interface"]

node_student -->|"enters credentials"| node_browser
node_browser -->|"loads options"| node_school_list
node_browser -.->|"requests subscription"| node_api
node_student -->|"requests ICS"| node_api
node_api -->|"calls generator"| node_engine
node_engine -->|"reads or updates"| node_cache
node_engine -->|"requests timetable"| node_dispatcher
node_dispatcher -->|"loads adapter"| node_adapter
node_adapter -->|"loads settings"| node_school_config
node_adapter -->|"authenticates and fetches"| node_portal
node_adapter -->|"encrypts credentials"| node_des
node_engine -->|"loads schedule"| node_timetable_config
node_engine -->|"reads term dates"| node_calendar_data
node_engine -->|"generates calendar"| node_ics
node_api -->|"returns calendar"| node_ics
node_ics -->|"subscribes or imports"| node_calendar_app
node_cli -->|"runs locally"| node_engine
node_sync -->|"fetches term dates"| node_public_calendar
node_sync -->|"writes dates"| node_calendar_data

click node_browser "https://github.com/shutdown-awa/xiqueer2ics/blob/main/web/scripts.js"
click node_school_list "https://github.com/shutdown-awa/xiqueer2ics/blob/main/web/schools.json"
click node_api "https://github.com/shutdown-awa/xiqueer2ics/blob/main/api.py"
click node_engine "https://github.com/shutdown-awa/xiqueer2ics/blob/main/xqe.py"
click node_cache "https://github.com/shutdown-awa/xiqueer2ics/blob/main/xqe.py"
click node_dispatcher "https://github.com/shutdown-awa/xiqueer2ics/blob/main/xqe.py"
click node_adapter "https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/main.py"
click node_des "https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/jkingo_des.py"
click node_school_config "https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/config.json"
click node_timetable_config "https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/timetable.json"
click node_calendar_data "https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/school_calendar.json"
click node_sync "https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/maintain.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_browser,node_school_list,node_api,node_cli toneBlue
class node_engine,node_cache,node_ics toneAmber
class node_dispatcher,node_adapter,node_des,node_school_config,node_timetable_config toneMint
class node_calendar_data,node_sync toneRose
class node_student,node_calendar_app,node_portal,node_public_calendar toneIndigo
```

## Components

### Web subscription

- [Browser UI](https://github.com/shutdown-awa/xiqueer2ics/blob/main/web/scripts.js): `web/scripts.js`
- [School list](https://github.com/shutdown-awa/xiqueer2ics/blob/main/web/schools.json): `web/schools.json`
- [ICS API](https://github.com/shutdown-awa/xiqueer2ics/blob/main/api.py): `api.py`

### Timetable to ICS

- [Timetable and ICS](https://github.com/shutdown-awa/xiqueer2ics/blob/main/xqe.py): `xqe.py`
- [User timetable cache](https://github.com/shutdown-awa/xiqueer2ics/blob/main/xqe.py): `xqe.py`
- **ICS calendar**

### School integration

- [School dispatcher](https://github.com/shutdown-awa/xiqueer2ics/blob/main/xqe.py): `xqe.py`
- [School timetable adapter](https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/main.py): `schools/12623/main.py`
- [Kingo DES](https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/jkingo_des.py): `schools/12623/jkingo_des.py`
- [School configuration](https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/config.json): `schools/12623/config.json`
- [Timetable settings](https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/timetable.json): `schools/12623/timetable.json`

### Calendar maintenance

- [School calendar data](https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/school_calendar.json): `schools/12623/school_calendar.json`
- [School calendar sync](https://github.com/shutdown-awa/xiqueer2ics/blob/main/schools/12623/maintain.py): `schools/12623/maintain.py`

### Other components

- **Student**
- **Calendar app**
- **Local script user**
- **Academic system**
- **Public calendar interface**

## Connections

- Student → Browser UI: enters credentials
- Browser UI → School list: loads options
- Browser UI → ICS API: requests subscription
- Student → ICS API: requests ICS
- ICS API → Timetable and ICS: calls generator
- Timetable and ICS → User timetable cache: reads or updates
- Timetable and ICS → School dispatcher: requests timetable
- School dispatcher → School timetable adapter: loads adapter
- School timetable adapter → School configuration: loads settings
- School timetable adapter → Academic system: authenticates and fetches
- School timetable adapter → Kingo DES: encrypts credentials
- Timetable and ICS → Timetable settings: loads schedule
- Timetable and ICS → School calendar data: reads term dates
- Timetable and ICS → ICS calendar: generates calendar
- ICS API → ICS calendar: returns calendar
- ICS calendar → Calendar app: subscribes or imports
- Local script user → Timetable and ICS: runs locally
- School calendar sync → Public calendar interface: fetches term dates
- School calendar sync → School calendar data: writes dates