# hoverclub/timer-controller architecture

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

- Interactive diagram: https://gitdiagram.com/hoverclub/timer-controller
- Repository: https://github.com/hoverclub/timer-controller

## Overview

This is an ESP8266/ESP32 programmable timer controller. Users configure Wi-Fi, then use the web interface to define controls, schedules, and sensor conditions; the device evaluates timers and sensor readings to drive physical outputs. The graph preserves documented display, backup/restore, and network-time capabilities. Source excerpts show the web routes, persistence API, hardware setup, and time setup; links for unsampled modules rely only on explicit README statements or are omitted where ownership is unclear.

Main entry points: [`src/webPages.cpp`](https://github.com/hoverclub/timer-controller/blob/main/src/webPages.cpp) (Web routes), [`src/main.cpp`](https://github.com/hoverclub/timer-controller/blob/main/src/main.cpp) (Startup coordinator), [`src/timerControl.cpp`](https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp) (Network time), [`data/timer.js`](https://github.com/hoverclub/timer-controller/blob/main/data/timer.js) (Browser interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Device setup"]
  node_boot["Startup coordinator<br/>[main.cpp]"]
  node_wifi["Wi-Fi provisioning<br/>[wifiConfig.cpp]"]
  node_clock["Network time<br/>[timerControl.cpp]"]
  node_timezone["POSIX time zones<br/>[tzPosix.cpp]"]
  node_debug["Debug output<br/>[DebugOut.cpp]"]
end

subgraph group_interface["Web configuration"]
  node_web["Web routes<br/>[webPages.cpp]"]
  node_browser["Browser interface<br/>[timer.js]"]
  node_webassets["Web page assets<br/>[index.html]"]
  node_settings["Controller settings<br/>[webPages.cpp]"]
  node_config["Controls and schedules<br/>[webPages.cpp]"]
  node_backup["Config backup<br/>[webPages.cpp]"]
end

subgraph group_schedule["Timer operation"]
  node_persistence[("Config persistence<br/>[timerControl.cpp]")]
  node_timerengine["Timer evaluation<br/>[timerControl.cpp]"]
end

subgraph group_hardware["I/O and display"]
  node_sensorread["Sensor sampling<br/>[timerControl.cpp]"]
  node_outputs["Output control<br/>[timerControl.cpp]"]
  node_pindefs["Pin definitions<br/>[pinDefs.cpp]"]
  node_oled["OLED setup display<br/>[wifiConfig.cpp]"]
end

node_owner(("Local user"))
node_ntp{{"NTP servers"}}
node_actuators{{"GPIO and I2C devices"}}

node_owner -->|"provisions network"| node_wifi
node_boot -->|"initializes"| node_wifi
node_boot -->|"starts server"| node_web
node_boot -->|"starts time sync"| node_clock
node_clock -->|"synchronizes time"| node_ntp
node_owner -->|"configures device"| node_browser
node_browser -->|"requests routes"| node_web
node_web -->|"serves assets"| node_webassets
node_web -->|"handles settings"| node_settings
node_web -->|"handles updates"| node_config
node_web -.->|"supports backup"| node_backup
node_config -->|"saves configuration"| node_persistence
node_boot -->|"loads configuration"| node_persistence
node_settings -->|"sets time zone"| node_timezone
node_clock -->|"cleans time zone"| node_timezone
node_timerengine -.->|"reads schedules"| node_persistence
node_timerengine -.->|"checks sensor conditions"| node_sensorread
node_sensorread -.->|"uses pin definitions"| node_pindefs
node_outputs -.->|"drives outputs"| node_actuators
node_boot -->|"initializes sensor I/O"| node_pindefs
node_oled -.->|"shows setup address"| node_owner

click node_boot "https://github.com/hoverclub/timer-controller/blob/main/src/main.cpp"
click node_wifi "https://github.com/hoverclub/timer-controller/blob/main/src/wifiConfig.cpp"
click node_clock "https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp"
click node_timezone "https://github.com/hoverclub/timer-controller/blob/main/src/tzPosix.cpp"
click node_web "https://github.com/hoverclub/timer-controller/blob/main/src/webPages.cpp"
click node_browser "https://github.com/hoverclub/timer-controller/blob/main/data/timer.js"
click node_webassets "https://github.com/hoverclub/timer-controller/blob/main/data/index.html"
click node_settings "https://github.com/hoverclub/timer-controller/blob/main/src/webPages.cpp"
click node_config "https://github.com/hoverclub/timer-controller/blob/main/src/webPages.cpp"
click node_backup "https://github.com/hoverclub/timer-controller/blob/main/src/webPages.cpp"
click node_persistence "https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp"
click node_timerengine "https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp"
click node_sensorread "https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp"
click node_outputs "https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp"
click node_pindefs "https://github.com/hoverclub/timer-controller/blob/main/src/pinDefs.cpp"
click node_oled "https://github.com/hoverclub/timer-controller/blob/main/src/wifiConfig.cpp"
click node_debug "https://github.com/hoverclub/timer-controller/blob/main/src/DebugOut.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_boot,node_wifi,node_clock,node_timezone,node_debug,node_owner toneBlue
class node_web,node_browser,node_webassets,node_settings,node_config,node_backup toneAmber
class node_persistence,node_timerengine,node_ntp toneMint
class node_sensorread,node_outputs,node_pindefs,node_oled toneRose
class node_actuators toneIndigo
```

## Components

### Device setup

- [Startup coordinator](https://github.com/hoverclub/timer-controller/blob/main/src/main.cpp): `src/main.cpp`
- [Wi-Fi provisioning](https://github.com/hoverclub/timer-controller/blob/main/src/wifiConfig.cpp): `src/wifiConfig.cpp`
- [Network time](https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp): `src/timerControl.cpp`
- [POSIX time zones](https://github.com/hoverclub/timer-controller/blob/main/src/tzPosix.cpp): `src/tzPosix.cpp`
- [Debug output](https://github.com/hoverclub/timer-controller/blob/main/src/DebugOut.cpp): `src/DebugOut.cpp`

### Web configuration

- [Web routes](https://github.com/hoverclub/timer-controller/blob/main/src/webPages.cpp): `src/webPages.cpp`
- [Browser interface](https://github.com/hoverclub/timer-controller/blob/main/data/timer.js): `data/timer.js`
- [Web page assets](https://github.com/hoverclub/timer-controller/blob/main/data/index.html): `data/index.html`
- [Controller settings](https://github.com/hoverclub/timer-controller/blob/main/src/webPages.cpp): `src/webPages.cpp`
- [Controls and schedules](https://github.com/hoverclub/timer-controller/blob/main/src/webPages.cpp): `src/webPages.cpp`
- [Config backup](https://github.com/hoverclub/timer-controller/blob/main/src/webPages.cpp): `src/webPages.cpp`

### Timer operation

- [Config persistence](https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp): `src/timerControl.cpp`
- [Timer evaluation](https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp): `src/timerControl.cpp`

### I/O and display

- [Sensor sampling](https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp): `src/timerControl.cpp`
- [Output control](https://github.com/hoverclub/timer-controller/blob/main/src/timerControl.cpp): `src/timerControl.cpp`
- [Pin definitions](https://github.com/hoverclub/timer-controller/blob/main/src/pinDefs.cpp): `src/pinDefs.cpp`
- [OLED setup display](https://github.com/hoverclub/timer-controller/blob/main/src/wifiConfig.cpp): `src/wifiConfig.cpp`

### Other components

- **Local user**
- **NTP servers**
- **GPIO and I2C devices**

## Connections

- Local user → Wi-Fi provisioning: provisions network (evidence: `README.MD`)
- Startup coordinator → Wi-Fi provisioning: initializes (evidence: `src/main.cpp`)
- Startup coordinator → Web routes: starts server (evidence: `src/main.cpp`)
- Startup coordinator → Network time: starts time sync (evidence: `src/main.cpp`)
- Network time → NTP servers: synchronizes time (evidence: `README.MD`)
- Local user → Browser interface: configures device (evidence: `README.MD`)
- Browser interface → Web routes: requests routes (evidence: `src/webPages.cpp`)
- Web routes → Web page assets: serves assets (evidence: `src/webPages.cpp`)
- Web routes → Controller settings: handles settings (evidence: `src/webPages.cpp`)
- Web routes → Controls and schedules: handles updates (evidence: `src/webPages.cpp`)
- Web routes → Config backup: supports backup (evidence: `README.MD`)
- Controls and schedules → Config persistence: saves configuration (evidence: `src/webPages.cpp`)
- Startup coordinator → Config persistence: loads configuration (evidence: `src/main.cpp`)
- Controller settings → POSIX time zones: sets time zone (evidence: `src/webPages.cpp`)
- Network time → POSIX time zones: cleans time zone (evidence: `src/timerControl.cpp`)
- Timer evaluation → Config persistence: reads schedules (evidence: `src/timerControl.cpp`)
- Timer evaluation → Sensor sampling: checks sensor conditions (evidence: `src/timerControl.cpp`)
- Sensor sampling → Pin definitions: uses pin definitions
- Output control → GPIO and I2C devices: drives outputs (evidence: `README.MD`)
- Startup coordinator → Pin definitions: initializes sensor I/O (evidence: `src/main.cpp`)
- OLED setup display → Local user: shows setup address (evidence: `README.MD`)