# times-z/geekmagic-open-firmware architecture

> Architecture diagram of the GitHub repository times-z/geekmagic-open-firmware, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/times-z/geekmagic-open-firmware
- Repository: https://github.com/times-z/geekmagic-open-firmware

## Overview

GeekMagic Open Firmware replaces the stock interface on HelloCubic Lite and Smalltv-Ultra ESP8266 displays. At boot, firmware loads configuration, initializes the display and Wi-Fi, starts time synchronization and the web server, and optionally starts the metrics dashboard; its loop services display, rescue mode, and dashboard updates. The web UI exposes configuration and device-management features, including Wi-Fi, rotation, NTP, GIF upload, logs, tokens, reboot, and OTA. Several subsystem links are documented by the source index rather than shown in excerpts, so those edges are omitted or marked unverified.

Main entry points: [`src/main.cpp`](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/main.cpp) (Firmware Runtime), [`src/display/DisplayManager.cpp`](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/display/DisplayManager.cpp) (Display Manager), [`src/web/Webserver.cpp`](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/web/Webserver.cpp) (HTTP Server), [`src/dashboard/DashboardManager.cpp`](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/dashboard/DashboardManager.cpp) (Metrics Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Boot and Recovery"]
  node_main["Firmware Runtime<br/>[main.cpp]"]
  node_rescue["Rescue Mode<br/>[RescueMode.cpp]"]
end

subgraph group_device["Device Services"]
  node_config["Configuration<br/>[ConfigManager.cpp]"]
  node_secure["Secure Storage<br/>[SecureStorage.cpp]"]
  node_eeprom[("EEPROM")]
  node_wifi["Wi-Fi Manager<br/>[WiFiManager.cpp]"]
  node_ntp["Time Sync<br/>[NTPClient.cpp]"]
  node_filesystem[("LittleFS")]
  node_logger["Logger<br/>[Logger.cpp]"]
end

subgraph group_web["Web Management"]
  node_webserver["HTTP Server<br/>[Webserver.cpp]"]
  node_api["Management API<br/>[Api.cpp]"]
  node_web_ui["Web Interface<br/>[index.html]"]
  node_web_assets["Web Feature Handlers"]
end

subgraph group_display["Screen and Dashboard"]
  node_display["Display Manager<br/>[DisplayManager.cpp]"]
  node_gif["GIF Playback<br/>[Gif.cpp]"]
  node_dashboard["Metrics Dashboard"]
end

node_device_user(("Device Owner"))
node_metrics_service["Metrics Service"]
node_browser(("Browser"))

node_device_user -->|"boots device"| node_main
node_main -->|"loads settings"| node_config
node_config -->|"uses credentials store"| node_secure
node_secure -->|"reads and writes"| node_eeprom
node_main -->|"checks boot state"| node_rescue
node_main -->|"initializes and updates"| node_display
node_main -->|"starts connectivity"| node_wifi
node_main -->|"starts time sync"| node_ntp
node_main -->|"configures server"| node_webserver
node_main -->|"starts and updates"| node_dashboard
node_webserver -.->|"routes requests"| node_api
node_browser -->|"opens interface"| node_web_ui
node_web_ui -.->|"loads handlers"| node_web_assets
node_web_assets -.->|"calls management endpoints"| node_api
node_webserver -->|"serves static files"| node_filesystem
node_main -->|"mounts filesystem"| node_filesystem
node_display -->|"plays animations"| node_gif
node_dashboard -->|"draws metrics"| node_display
node_dashboard -->|"fetches metrics"| node_metrics_service
node_wifi -->|"renders connection status"| node_display
node_main -.->|"logs runtime events"| node_logger

click node_main "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/main.cpp"
click node_rescue "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/boot/RescueMode.cpp"
click node_config "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/config/ConfigManager.cpp"
click node_secure "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/config/SecureStorage.cpp"
click node_wifi "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/wireless/WiFiManager.cpp"
click node_ntp "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/ntp/NTPClient.cpp"
click node_webserver "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/web/Webserver.cpp"
click node_api "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/web/Api.cpp"
click node_web_ui "https://github.com/times-z/geekmagic-open-firmware/blob/develop/data/web/index.html"
click node_web_assets "https://github.com/times-z/geekmagic-open-firmware/tree/develop/data/web/js"
click node_display "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/display/DisplayManager.cpp"
click node_gif "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/display/Gif.cpp"
click node_dashboard "https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/dashboard/DashboardManager.cpp"
click node_logger "https://github.com/times-z/geekmagic-open-firmware/blob/develop/lib/Logger/Logger.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_main,node_rescue,node_browser toneBlue
class node_config,node_secure,node_eeprom,node_wifi,node_ntp,node_filesystem,node_logger toneAmber
class node_webserver,node_api,node_web_ui,node_web_assets toneMint
class node_display,node_gif,node_dashboard toneRose
class node_device_user,node_metrics_service toneIndigo
```

## Components

### Boot and Recovery

- [Firmware Runtime](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/main.cpp): `src/main.cpp`
- [Rescue Mode](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/boot/RescueMode.cpp): `src/boot/RescueMode.cpp`

### Device Services

- [Configuration](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/config/ConfigManager.cpp): `src/config/ConfigManager.cpp`
- [Secure Storage](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/config/SecureStorage.cpp): `src/config/SecureStorage.cpp`
- **EEPROM**
- [Wi-Fi Manager](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/wireless/WiFiManager.cpp): `src/wireless/WiFiManager.cpp`
- [Time Sync](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/ntp/NTPClient.cpp): `src/ntp/NTPClient.cpp`
- **LittleFS**
- [Logger](https://github.com/times-z/geekmagic-open-firmware/blob/develop/lib/Logger/Logger.cpp): `lib/Logger/Logger.cpp`

### Web Management

- [HTTP Server](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/web/Webserver.cpp): `src/web/Webserver.cpp`
- [Management API](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/web/Api.cpp): `src/web/Api.cpp`
- [Web Interface](https://github.com/times-z/geekmagic-open-firmware/blob/develop/data/web/index.html): `data/web/index.html`
- [Web Feature Handlers](https://github.com/times-z/geekmagic-open-firmware/tree/develop/data/web/js): `data/web/js`

### Screen and Dashboard

- [Display Manager](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/display/DisplayManager.cpp): `src/display/DisplayManager.cpp`
- [GIF Playback](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/display/Gif.cpp): `src/display/Gif.cpp`
- [Metrics Dashboard](https://github.com/times-z/geekmagic-open-firmware/blob/develop/src/dashboard/DashboardManager.cpp): `src/dashboard/DashboardManager.cpp`

### Other components

- **Device Owner**
- **Metrics Service**
- **Browser**

## Connections

- Device Owner → Firmware Runtime: boots device (evidence: `readme.md`)
- Firmware Runtime → Configuration: loads settings (evidence: `src/main.cpp`)
- Configuration → Secure Storage: uses credentials store
- Secure Storage → EEPROM: reads and writes (evidence: `src/config/SecureStorage.cpp`)
- Firmware Runtime → Rescue Mode: checks boot state (evidence: `src/main.cpp`)
- Firmware Runtime → Display Manager: initializes and updates (evidence: `src/main.cpp`)
- Firmware Runtime → Wi-Fi Manager: starts connectivity (evidence: `src/main.cpp`)
- Firmware Runtime → Time Sync: starts time sync (evidence: `src/main.cpp`)
- Firmware Runtime → HTTP Server: configures server (evidence: `src/main.cpp`)
- Firmware Runtime → Metrics Dashboard: starts and updates (evidence: `src/main.cpp`)
- HTTP Server → Management API: routes requests
- Browser → Web Interface: opens interface (evidence: `readme.md`)
- Web Interface → Web Feature Handlers: loads handlers
- Web Feature Handlers → Management API: calls management endpoints
- HTTP Server → LittleFS: serves static files
- Firmware Runtime → LittleFS: mounts filesystem (evidence: `src/main.cpp`)
- Display Manager → GIF Playback: plays animations (evidence: `src/display/DisplayManager.cpp`)
- Metrics Dashboard → Display Manager: draws metrics (evidence: `src/dashboard/DashboardManager.cpp`)
- Metrics Dashboard → Metrics Service: fetches metrics (evidence: `src/dashboard/DashboardManager.cpp`)
- Wi-Fi Manager → Display Manager: renders connection status (evidence: `src/wireless/WiFiManager.cpp`)
- Firmware Runtime → Logger: logs runtime events
