# gklier/kliercalendar architecture

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

- Interactive diagram: https://gitdiagram.com/gklier/kliercalendar
- Repository: https://github.com/gklier/kliercalendar

## Overview

Family Dashboard combines a Python server that keeps settings and credentials, fetches calendar/weather/traffic/stock data, and serves APIs with a browser-based TV display and phone-friendly admin. The main workflow is configure sources and appearance in admin, fetch and serve live data, then render it on the TV; the Pi launcher also handles sleep state and optional hosted-screen fallback. README statements establish the broad service/API links; sampled code confirms TV mode selection, admin API usage, layout preview messaging, and schedule behavior. Several server subsystems are documented but not independently sampled.

Main entry points: [`server/server.py`](https://github.com/gklier/kliercalendar/blob/main/server/server.py) (HTTP API and config), [`pi/kiosk.sh`](https://github.com/gklier/kliercalendar/blob/main/pi/kiosk.sh) (Kiosk launcher), [`web/app.js`](https://github.com/gklier/kliercalendar/blob/main/web/app.js) (TV dashboard runtime), [`web/admin/pages-layout.js`](https://github.com/gklier/kliercalendar/blob/main/web/admin/pages-layout.js) (Layout editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Settings and administration"]
  node_admin_ui["Admin settings UI<br/>[admin.js]"]
  node_look["Look editor<br/>[pages-look.js]"]
  node_layout["Layout editor<br/>[pages-layout.js]"]
  node_schedule_ui["Schedule controls<br/>[pages-schedule.js]"]
  node_ops_ui["Backup and help<br/>[pages-ops.js]"]
end

subgraph group_server["Dashboard server"]
  node_server_api["HTTP API and config<br/>[server.py]"]
  node_calendar["Calendar collection<br/>[server.py]"]
  node_weather["Weather fetch<br/>[server.py]"]
  node_journeys["Drive-time calculation<br/>[server.py]"]
  node_stocks["Stock quotes<br/>[server.py]"]
  node_settings_store[("Settings and media<br/>[server.py]")]
end

subgraph group_feeds["Live data sources"]
  node_calendar_service["Google Calendar / CalDAV"]
  node_maps_service["Google Maps Routes"]
  node_tempest["Tempest station"]
  node_finnhub["Finnhub quotes"]
end

subgraph group_display["TV display"]
  node_tv_runtime["TV dashboard runtime<br/>[app.js]"]
  node_demo_data["Demo data mode<br/>[demo.js]"]
  node_icons["Weather and place icons<br/>[icons.js]"]
end

subgraph group_pi["Pi operation"]
  node_pi_launcher["Kiosk launcher<br/>[kiosk.sh]"]
  node_pi_setup["Kiosk setup<br/>[kiosk_setup.py]"]
end

node_family(("Family / settings user"))
node_maintainer(("System maintainer"))
node_hosted_fallback["Hosted dashboard fallback"]
node_tv_screen(("Living-room TV"))
node_admin_browser(("Phone / browser"))

node_family -->|"opens settings"| node_admin_browser
node_admin_browser -->|"uses"| node_admin_ui
node_admin_ui -->|"sends settings"| node_server_api
node_look -->|"saves appearance"| node_server_api
node_layout -->|"previews layout"| node_tv_runtime
node_layout -->|"saves layout"| node_server_api
node_schedule_ui -->|"updates schedule"| node_server_api
node_ops_ui -->|"requests backup"| node_server_api
node_server_api -->|"reads and writes"| node_settings_store
node_server_api -->|"serves calendar data"| node_calendar
node_server_api -->|"serves weather data"| node_weather
node_server_api -->|"serves drive times"| node_journeys
node_server_api -->|"serves stock data"| node_stocks
node_calendar -->|"fetches calendars"| node_calendar_service
node_weather -->|"fetches conditions"| node_tempest
node_journeys -->|"requests routes"| node_maps_service
node_stocks -->|"fetches quotes"| node_finnhub
node_tv_runtime -->|"loads live data"| node_server_api
node_tv_runtime -->|"uses demo mode"| node_demo_data
node_tv_runtime -.->|"renders glyphs"| node_icons
node_pi_launcher -->|"polls status"| node_server_api
node_pi_launcher -->|"opens dashboard"| node_tv_runtime
node_server_api -->|"provides sleep state"| node_pi_launcher
node_pi_setup -.->|"configures kiosk"| node_pi_launcher
node_pi_launcher -->|"drives display"| node_tv_screen
node_pi_launcher -.->|"falls back to"| node_hosted_fallback
node_maintainer -->|"uses recovery tools"| node_ops_ui

click node_admin_ui "https://github.com/gklier/kliercalendar/blob/main/web/admin/admin.js"
click node_look "https://github.com/gklier/kliercalendar/blob/main/web/admin/pages-look.js"
click node_layout "https://github.com/gklier/kliercalendar/blob/main/web/admin/pages-layout.js"
click node_schedule_ui "https://github.com/gklier/kliercalendar/blob/main/web/admin/pages-schedule.js"
click node_ops_ui "https://github.com/gklier/kliercalendar/blob/main/web/admin/pages-ops.js"
click node_server_api "https://github.com/gklier/kliercalendar/blob/main/server/server.py"
click node_calendar "https://github.com/gklier/kliercalendar/blob/main/server/server.py"
click node_weather "https://github.com/gklier/kliercalendar/blob/main/server/server.py"
click node_journeys "https://github.com/gklier/kliercalendar/blob/main/server/server.py"
click node_stocks "https://github.com/gklier/kliercalendar/blob/main/server/server.py"
click node_settings_store "https://github.com/gklier/kliercalendar/blob/main/server/server.py"
click node_tv_runtime "https://github.com/gklier/kliercalendar/blob/main/web/app.js"
click node_demo_data "https://github.com/gklier/kliercalendar/blob/main/web/demo.js"
click node_icons "https://github.com/gklier/kliercalendar/blob/main/web/icons.js"
click node_pi_launcher "https://github.com/gklier/kliercalendar/blob/main/pi/kiosk.sh"
click node_pi_setup "https://github.com/gklier/kliercalendar/blob/main/pi/kiosk_setup.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_admin_ui,node_look,node_layout,node_schedule_ui,node_ops_ui,node_family,node_admin_browser toneBlue
class node_server_api,node_calendar,node_weather,node_journeys,node_stocks,node_settings_store toneAmber
class node_calendar_service,node_maps_service,node_tempest,node_finnhub toneMint
class node_tv_runtime,node_demo_data,node_icons toneRose
class node_pi_launcher,node_pi_setup,node_maintainer,node_hosted_fallback,node_tv_screen toneIndigo
```

## Components

### Settings and administration

- [Admin settings UI](https://github.com/gklier/kliercalendar/blob/main/web/admin/admin.js): `web/admin/admin.js`
- [Look editor](https://github.com/gklier/kliercalendar/blob/main/web/admin/pages-look.js): `web/admin/pages-look.js`
- [Layout editor](https://github.com/gklier/kliercalendar/blob/main/web/admin/pages-layout.js): `web/admin/pages-layout.js`
- [Schedule controls](https://github.com/gklier/kliercalendar/blob/main/web/admin/pages-schedule.js): `web/admin/pages-schedule.js`
- [Backup and help](https://github.com/gklier/kliercalendar/blob/main/web/admin/pages-ops.js): `web/admin/pages-ops.js`

### Dashboard server

- [HTTP API and config](https://github.com/gklier/kliercalendar/blob/main/server/server.py): `server/server.py`
- [Calendar collection](https://github.com/gklier/kliercalendar/blob/main/server/server.py): `server/server.py`
- [Weather fetch](https://github.com/gklier/kliercalendar/blob/main/server/server.py): `server/server.py`
- [Drive-time calculation](https://github.com/gklier/kliercalendar/blob/main/server/server.py): `server/server.py`
- [Stock quotes](https://github.com/gklier/kliercalendar/blob/main/server/server.py): `server/server.py`
- [Settings and media](https://github.com/gklier/kliercalendar/blob/main/server/server.py): `server/server.py`

### Live data sources

- **Google Calendar / CalDAV**
- **Google Maps Routes**
- **Tempest station**
- **Finnhub quotes**

### TV display

- [TV dashboard runtime](https://github.com/gklier/kliercalendar/blob/main/web/app.js): `web/app.js`
- [Demo data mode](https://github.com/gklier/kliercalendar/blob/main/web/demo.js): `web/demo.js`
- [Weather and place icons](https://github.com/gklier/kliercalendar/blob/main/web/icons.js): `web/icons.js`

### Pi operation

- [Kiosk launcher](https://github.com/gklier/kliercalendar/blob/main/pi/kiosk.sh): `pi/kiosk.sh`
- [Kiosk setup](https://github.com/gklier/kliercalendar/blob/main/pi/kiosk_setup.py): `pi/kiosk_setup.py`

### Other components

- **Family / settings user**
- **System maintainer**
- **Hosted dashboard fallback**
- **Living-room TV**
- **Phone / browser**

## Connections

- Family / settings user → Phone / browser: opens settings (evidence: `README.md`)
- Phone / browser → Admin settings UI: uses (evidence: `README.md`)
- Admin settings UI → HTTP API and config: sends settings (evidence: `web/admin/admin.js`)
- Look editor → HTTP API and config: saves appearance (evidence: `README.md`)
- Layout editor → TV dashboard runtime: previews layout (evidence: `web/admin/pages-layout.js`)
- Layout editor → HTTP API and config: saves layout (evidence: `README.md`)
- Schedule controls → HTTP API and config: updates schedule (evidence: `web/admin/pages-schedule.js`)
- Backup and help → HTTP API and config: requests backup (evidence: `README.md`)
- HTTP API and config → Settings and media: reads and writes (evidence: `README.md`)
- HTTP API and config → Calendar collection: serves calendar data (evidence: `README.md`)
- HTTP API and config → Weather fetch: serves weather data (evidence: `README.md`)
- HTTP API and config → Drive-time calculation: serves drive times (evidence: `README.md`)
- HTTP API and config → Stock quotes: serves stock data (evidence: `README.md`)
- Calendar collection → Google Calendar / CalDAV: fetches calendars (evidence: `README.md`)
- Weather fetch → Tempest station: fetches conditions (evidence: `README.md`)
- Drive-time calculation → Google Maps Routes: requests routes (evidence: `README.md`)
- Stock quotes → Finnhub quotes: fetches quotes (evidence: `README.md`)
- TV dashboard runtime → HTTP API and config: loads live data (evidence: `README.md`)
- TV dashboard runtime → Demo data mode: uses demo mode (evidence: `web/app.js`)
- TV dashboard runtime → Weather and place icons: renders glyphs
- Kiosk launcher → HTTP API and config: polls status (evidence: `README.md`)
- Kiosk launcher → TV dashboard runtime: opens dashboard (evidence: `README.md`)
- HTTP API and config → Kiosk launcher: provides sleep state
- Kiosk setup → Kiosk launcher: configures kiosk
- Kiosk launcher → Living-room TV: drives display (evidence: `README.md`)
- Kiosk launcher → Hosted dashboard fallback: falls back to (evidence: `README.md`)
- System maintainer → Backup and help: uses recovery tools (evidence: `README.md`)
