# oe9mdv/wordclock architecture

> Architecture diagram of the GitHub repository oe9mdv/wordclock, 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/oe9mdv/wordclock
- Repository: https://github.com/oe9mdv/wordclock

## Overview

WordClock is an ESP8266-based German word clock: users provision Wi-Fi, configure the clock in its browser interface, and see the current time rendered on an LED word grid. Its main stages are network setup and web requests, saved color/time/DND settings, time and timezone acquisition, language-specific phrase selection, and physical LED output; startup health checking is also a documented feature. The sampled controller and renderers support several links below; wiring inside unsampled runtime modules is represented only where documented or otherwise evident from the repository tree and README.

Main entry points: [`wordclock/src/controller.cpp`](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/controller.cpp) (Request controller), [`wordclock/src/grid.cpp`](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/grid.cpp) (Language dispatch), [`wordclock/src/led.cpp`](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/led.cpp) (LED mapping), [`wordclock/src/wifi.cpp`](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/wifi.cpp) (Wi-Fi setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_network["Network and UI"]
  node_wifi["Wi-Fi setup<br/>[wifi.cpp]"]
  node_server["HTTP server<br/>[httpServer.cpp]"]
  node_gui["Settings interface<br/>[gui.cpp]"]
  node_controller["Request controller<br/>[controller.cpp]"]
  node_main["Device runtime<br/>[wordclock.ino]"]
end

subgraph group_settings["Clock settings"]
  node_config[("Persistent settings<br/>[config.cpp]")]
  node_color["Color conversion<br/>[color.cpp]"]
  node_dnd["Do-not-disturb<br/>[dnd.cpp]"]
  node_healthcheck["LED health check<br/>[healthcheck.cpp]"]
end

subgraph group_time["Time and language"]
  node_ntp["Network time<br/>[time.cpp]"]
  node_offset["Timezone offset<br/>[utcOffset.cpp]"]
  node_grid["Language dispatch<br/>[grid.cpp]"]
  node_german["German layouts<br/>[de_DE.cpp]"]
  node_alt["Alternate layouts<br/>[de_DE_alt.cpp]"]
  node_round["Rounded layout<br/>[de_DE_round.cpp]"]
  node_s_layouts["Simplified layouts<br/>[de_DE_s.cpp]"]
  node_s1_layout["S1 layout<br/>[de_DE_s1.cpp]"]
end

subgraph group_display["LED display"]
  node_ledmap["LED mapping<br/>[led.cpp]"]
  node_leds(("LED strip"))
end

node_owner(("Clock owner"))
node_phone(("Phone browser"))
node_router(("Wi-Fi router"))
node_ntp_service(("NTP service"))
node_offset_service(("Timezone API"))

node_owner -->|"provisions"| node_wifi
node_phone -->|"sets credentials"| node_wifi
node_wifi -->|"joins network"| node_router
node_phone -->|"requests settings"| node_server
node_server -->|"dispatches"| node_controller
node_controller -->|"requests page"| node_gui
node_gui -->|"serves controls"| node_phone
node_controller -->|"converts colors"| node_color
node_controller -->|"saves settings"| node_config
node_controller -->|"updates offset"| node_offset
node_controller -->|"refreshes display"| node_grid
node_controller -->|"resets credentials"| node_wifi
node_main -->|"starts setup"| node_wifi
node_main -->|"starts server"| node_server
node_main -->|"starts timekeeping"| node_ntp
node_main -->|"runs check"| node_healthcheck
node_ntp -->|"synchronizes time"| node_ntp_service
node_offset -.->|"looks up offset"| node_offset_service
node_ntp -->|"reads time settings"| node_config
node_grid -->|"selects layout"| node_german
node_grid -.->|"selects layout"| node_alt
node_grid -.->|"selects layout"| node_round
node_grid -.->|"selects layout"| node_s_layouts
node_grid -.->|"selects layout"| node_s1_layout
node_german -->|"checks quiet hours"| node_dnd
node_alt -->|"checks quiet hours"| node_dnd
node_round -->|"checks quiet hours"| node_dnd
node_s_layouts -->|"checks quiet hours"| node_dnd
node_s1_layout -->|"checks quiet hours"| node_dnd
node_german -->|"sets LED colors"| node_ledmap
node_alt -->|"sets LED colors"| node_ledmap
node_round -->|"sets LED colors"| node_ledmap
node_s_layouts -->|"sets LED colors"| node_ledmap
node_s1_layout -->|"sets LED colors"| node_ledmap
node_ledmap -->|"drives strip"| node_leds
node_healthcheck -->|"tests LEDs"| node_leds

click node_wifi "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/wifi.cpp"
click node_server "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/httpServer.cpp"
click node_gui "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/gui.cpp"
click node_controller "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/controller.cpp"
click node_main "https://github.com/oe9mdv/wordclock/blob/master/wordclock/wordclock.ino"
click node_config "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/config.cpp"
click node_color "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/color.cpp"
click node_dnd "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/dnd.cpp"
click node_healthcheck "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/healthcheck.cpp"
click node_ntp "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/time.cpp"
click node_offset "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/utcOffset.cpp"
click node_grid "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/grid.cpp"
click node_german "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/language/de_DE.cpp"
click node_alt "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/language/de_DE_alt.cpp"
click node_round "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/language/de_DE_round.cpp"
click node_s_layouts "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/language/de_DE_s.cpp"
click node_s1_layout "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/language/de_DE_s1.cpp"
click node_ledmap "https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/led.cpp"

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_wifi,node_server,node_gui,node_controller,node_main,node_phone toneBlue
class node_config,node_color,node_dnd,node_healthcheck toneAmber
class node_ntp,node_offset,node_grid,node_german,node_alt,node_round,node_s_layouts,node_s1_layout,node_router,node_offset_service toneMint
class node_ledmap,node_leds toneRose
class node_owner,node_ntp_service toneIndigo
```

## Components

### Network and UI

- [Wi-Fi setup](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/wifi.cpp): `wordclock/src/wifi.cpp`
- [HTTP server](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/httpServer.cpp): `wordclock/src/httpServer.cpp`
- [Settings interface](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/gui.cpp): `wordclock/src/gui.cpp`
- [Request controller](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/controller.cpp): `wordclock/src/controller.cpp`
- [Device runtime](https://github.com/oe9mdv/wordclock/blob/master/wordclock/wordclock.ino): `wordclock/wordclock.ino`

### Clock settings

- [Persistent settings](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/config.cpp): `wordclock/src/config.cpp`
- [Color conversion](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/color.cpp): `wordclock/src/color.cpp`
- [Do-not-disturb](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/dnd.cpp): `wordclock/src/dnd.cpp`
- [LED health check](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/healthcheck.cpp): `wordclock/src/healthcheck.cpp`

### Time and language

- [Network time](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/time.cpp): `wordclock/src/time.cpp`
- [Timezone offset](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/utcOffset.cpp): `wordclock/src/utcOffset.cpp`
- [Language dispatch](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/grid.cpp): `wordclock/src/grid.cpp`
- [German layouts](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/language/de_DE.cpp): `wordclock/src/language/de_DE.cpp`
- [Alternate layouts](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/language/de_DE_alt.cpp): `wordclock/src/language/de_DE_alt.cpp`
- [Rounded layout](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/language/de_DE_round.cpp): `wordclock/src/language/de_DE_round.cpp`
- [Simplified layouts](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/language/de_DE_s.cpp): `wordclock/src/language/de_DE_s.cpp`
- [S1 layout](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/language/de_DE_s1.cpp): `wordclock/src/language/de_DE_s1.cpp`

### LED display

- [LED mapping](https://github.com/oe9mdv/wordclock/blob/master/wordclock/src/led.cpp): `wordclock/src/led.cpp`
- **LED strip**

### Other components

- **Clock owner**
- **Phone browser**
- **Wi-Fi router**
- **NTP service**
- **Timezone API**

## Connections

- Clock owner → Wi-Fi setup: provisions
- Phone browser → Wi-Fi setup: sets credentials
- Wi-Fi setup → Wi-Fi router: joins network
- Phone browser → HTTP server: requests settings
- HTTP server → Request controller: dispatches
- Request controller → Settings interface: requests page
- Settings interface → Phone browser: serves controls
- Request controller → Color conversion: converts colors
- Request controller → Persistent settings: saves settings
- Request controller → Timezone offset: updates offset
- Request controller → Language dispatch: refreshes display
- Request controller → Wi-Fi setup: resets credentials
- Device runtime → Wi-Fi setup: starts setup
- Device runtime → HTTP server: starts server
- Device runtime → Network time: starts timekeeping
- Device runtime → LED health check: runs check
- Network time → NTP service: synchronizes time
- Timezone offset → Timezone API: looks up offset
- Network time → Persistent settings: reads time settings
- Language dispatch → German layouts: selects layout
- Language dispatch → Alternate layouts: selects layout
- Language dispatch → Rounded layout: selects layout
- Language dispatch → Simplified layouts: selects layout
- Language dispatch → S1 layout: selects layout
- German layouts → Do-not-disturb: checks quiet hours
- Alternate layouts → Do-not-disturb: checks quiet hours
- Rounded layout → Do-not-disturb: checks quiet hours
- Simplified layouts → Do-not-disturb: checks quiet hours
- S1 layout → Do-not-disturb: checks quiet hours
- German layouts → LED mapping: sets LED colors
- Alternate layouts → LED mapping: sets LED colors
- Rounded layout → LED mapping: sets LED colors
- Simplified layouts → LED mapping: sets LED colors
- S1 layout → LED mapping: sets LED colors
- LED mapping → LED strip: drives strip
- LED health check → LED strip: tests LEDs