# keralots/animatedpixelclock architecture

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

- Interactive diagram: https://gitdiagram.com/keralots/animatedpixelclock
- Repository: https://github.com/keralots/animatedpixelclock

## Overview

AnimatedPixelClock is ESP32-S3 firmware for a 128×64 animated LED-matrix clock, with a desktop companion mode for live PC metrics. The main user workflow is selecting a clock or metrics display, configuring it through the web interface or companion app, and rendering the result on the matrix. Separate capabilities include weather, ambient animations, audio visualization, notifications, and an addressable LED strip. The README documents the product flows; source excerpts and the index support selected internal links, while unsampled implementation details are left unconnected.

Main entry points: [`PC-Companion-App-v4/win-companion/pc_stats_monitor_v4.py`](https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/win-companion/pc_stats_monitor_v4.py) (Desktop companion), [`src/display/display.cpp`](https://github.com/keralots/animatedpixelclock/blob/main/src/display/display.cpp) (Matrix display), [`src/main.cpp`](https://github.com/keralots/animatedpixelclock/blob/main/src/main.cpp) (Firmware runtime), [`src/metrics/metrics.cpp`](https://github.com/keralots/animatedpixelclock/blob/main/src/metrics/metrics.cpp) (Metrics renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Clock firmware"]
  node_main["Firmware runtime<br/>[main.cpp]"]
  node_clock_styles["Clock styles"]
  node_ambient["Ambient modes"]
  node_display["Matrix display<br/>[display.cpp]"]
  node_network["Wi-Fi and time<br/>[network.cpp]"]
  node_metrics["Metrics renderer<br/>[metrics.cpp]"]
end

subgraph group_configuration["Settings and interface"]
  node_settings[("Persistent settings<br/>[settings.cpp]")]
  node_web_api["Device web API<br/>[web.cpp]"]
  node_web_ui["Browser interface<br/>[web_pages.h]"]
end

subgraph group_companion["PC companion"]
  node_desktop_app["Desktop companion"]
  node_linux_app["Linux companion"]
  node_layout["Layout engine<br/>[layout_engine.py]"]
  node_companion_api["Companion web server<br/>[server.py]"]
  node_gif_transfer["Animation transfer"]
end

subgraph group_extras["Additional features"]
  node_weather["Weather service<br/>[weather.cpp]"]
  node_audio_viz["Audio visualizer<br/>[visualizer.cpp]"]
  node_led_strip["LED strip effects<br/>[led_strip.cpp]"]
  node_notifications["Notifications<br/>[notify.cpp]"]
  node_animation_store[("Animation storage<br/>[anim_store.cpp]")]
end

node_owner(("Clock owner"))
node_matrix_panels["RGB matrix panels"]
node_pc_sensors["PC sensors"]
node_weather_service["Weather provider"]

node_owner -->|"configures"| node_web_ui
node_web_ui -.->|"submits settings"| node_web_api
node_web_api -.->|"saves settings"| node_settings
node_main -->|"loads settings"| node_settings
node_main -->|"mounts storage"| node_animation_store
node_main -->|"initializes display"| node_display
node_main -.->|"selects renderer"| node_clock_styles
node_clock_styles -.->|"draws clock"| node_display
node_ambient -.->|"draws effects"| node_display
node_display -->|"renders pixels"| node_matrix_panels
node_owner -->|"configures monitoring"| node_desktop_app
node_pc_sensors -.->|"provides readings"| node_desktop_app
node_pc_sensors -.->|"provides readings"| node_linux_app
node_desktop_app -->|"builds layout"| node_layout
node_layout -->|"returns layout"| node_desktop_app
node_desktop_app -->|"sends stats"| node_metrics
node_linux_app -->|"sends stats"| node_metrics
node_metrics -.->|"renders metrics"| node_display
node_owner -->|"enables weather"| node_weather
node_weather -.->|"fetches forecast"| node_weather_service
node_audio_viz -->|"provides audio levels"| node_led_strip
node_owner -.->|"sends alerts"| node_notifications
node_desktop_app -->|"uses companion UI"| node_companion_api
node_owner -.->|"uploads animation"| node_gif_transfer
node_gif_transfer -.->|"transfers animation"| node_animation_store
node_network -.->|"hosts web service"| node_web_api

click node_main "https://github.com/keralots/animatedpixelclock/blob/main/src/main.cpp"
click node_clock_styles "https://github.com/keralots/animatedpixelclock/tree/main/src/clocks"
click node_ambient "https://github.com/keralots/animatedpixelclock/tree/main/src/ambient"
click node_display "https://github.com/keralots/animatedpixelclock/blob/main/src/display/display.cpp"
click node_settings "https://github.com/keralots/animatedpixelclock/blob/main/src/config/settings.cpp"
click node_web_api "https://github.com/keralots/animatedpixelclock/blob/main/src/web/web.cpp"
click node_web_ui "https://github.com/keralots/animatedpixelclock/blob/main/src/web/web_pages.h"
click node_network "https://github.com/keralots/animatedpixelclock/blob/main/src/network/network.cpp"
click node_weather "https://github.com/keralots/animatedpixelclock/blob/main/src/weather/weather.cpp"
click node_metrics "https://github.com/keralots/animatedpixelclock/blob/main/src/metrics/metrics.cpp"
click node_desktop_app "https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/win-companion/pc_stats_monitor_v4.py"
click node_linux_app "https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/linux-companion/pc_stats_monitor_v4_linux.py"
click node_layout "https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/companion-common/layout_engine.py"
click node_companion_api "https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/companion-common/server.py"
click node_audio_viz "https://github.com/keralots/animatedpixelclock/blob/main/src/viz/visualizer.cpp"
click node_led_strip "https://github.com/keralots/animatedpixelclock/blob/main/src/led/led_strip.cpp"
click node_notifications "https://github.com/keralots/animatedpixelclock/blob/main/src/notify/notify.cpp"
click node_animation_store "https://github.com/keralots/animatedpixelclock/blob/main/src/ambient/anim_store.cpp"
click node_gif_transfer "https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/companion-common/animation_service.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_main,node_clock_styles,node_ambient,node_display,node_network,node_metrics toneBlue
class node_settings,node_web_api,node_web_ui toneAmber
class node_desktop_app,node_linux_app,node_layout,node_companion_api,node_gif_transfer toneMint
class node_weather,node_audio_viz,node_led_strip,node_notifications,node_animation_store toneRose
class node_owner,node_matrix_panels,node_pc_sensors,node_weather_service toneIndigo
```

## Components

### Clock firmware

- [Firmware runtime](https://github.com/keralots/animatedpixelclock/blob/main/src/main.cpp): `src/main.cpp`
- [Clock styles](https://github.com/keralots/animatedpixelclock/tree/main/src/clocks): `src/clocks`
- [Ambient modes](https://github.com/keralots/animatedpixelclock/tree/main/src/ambient): `src/ambient`
- [Matrix display](https://github.com/keralots/animatedpixelclock/blob/main/src/display/display.cpp): `src/display/display.cpp`
- [Wi-Fi and time](https://github.com/keralots/animatedpixelclock/blob/main/src/network/network.cpp): `src/network/network.cpp`
- [Metrics renderer](https://github.com/keralots/animatedpixelclock/blob/main/src/metrics/metrics.cpp): `src/metrics/metrics.cpp`

### Settings and interface

- [Persistent settings](https://github.com/keralots/animatedpixelclock/blob/main/src/config/settings.cpp): `src/config/settings.cpp`
- [Device web API](https://github.com/keralots/animatedpixelclock/blob/main/src/web/web.cpp): `src/web/web.cpp`
- [Browser interface](https://github.com/keralots/animatedpixelclock/blob/main/src/web/web_pages.h): `src/web/web_pages.h`

### PC companion

- [Desktop companion](https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/win-companion/pc_stats_monitor_v4.py): `PC-Companion-App-v4/win-companion/pc_stats_monitor_v4.py`
- [Linux companion](https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/linux-companion/pc_stats_monitor_v4_linux.py): `PC-Companion-App-v4/linux-companion/pc_stats_monitor_v4_linux.py`
- [Layout engine](https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/companion-common/layout_engine.py): `PC-Companion-App-v4/companion-common/layout_engine.py`
- [Companion web server](https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/companion-common/server.py): `PC-Companion-App-v4/companion-common/server.py`
- [Animation transfer](https://github.com/keralots/animatedpixelclock/blob/main/PC-Companion-App-v4/companion-common/animation_service.py): `PC-Companion-App-v4/companion-common/animation_service.py`

### Additional features

- [Weather service](https://github.com/keralots/animatedpixelclock/blob/main/src/weather/weather.cpp): `src/weather/weather.cpp`
- [Audio visualizer](https://github.com/keralots/animatedpixelclock/blob/main/src/viz/visualizer.cpp): `src/viz/visualizer.cpp`
- [LED strip effects](https://github.com/keralots/animatedpixelclock/blob/main/src/led/led_strip.cpp): `src/led/led_strip.cpp`
- [Notifications](https://github.com/keralots/animatedpixelclock/blob/main/src/notify/notify.cpp): `src/notify/notify.cpp`
- [Animation storage](https://github.com/keralots/animatedpixelclock/blob/main/src/ambient/anim_store.cpp): `src/ambient/anim_store.cpp`

### Other components

- **Clock owner**
- **RGB matrix panels**
- **PC sensors**
- **Weather provider**

## Connections

- Clock owner → Browser interface: configures
- Browser interface → Device web API: submits settings
- Device web API → Persistent settings: saves settings
- Firmware runtime → Persistent settings: loads settings (evidence: `src/main.cpp`)
- Firmware runtime → Animation storage: mounts storage (evidence: `src/main.cpp`)
- Firmware runtime → Matrix display: initializes display (evidence: `src/main.cpp`)
- Firmware runtime → Clock styles: selects renderer (evidence: `src/main.cpp`)
- Clock styles → Matrix display: draws clock
- Ambient modes → Matrix display: draws effects
- Matrix display → RGB matrix panels: renders pixels
- Clock owner → Desktop companion: configures monitoring
- PC sensors → Desktop companion: provides readings
- PC sensors → Linux companion: provides readings
- Desktop companion → Layout engine: builds layout (evidence: `PC-Companion-App-v4/win-companion/pc_stats_monitor_v4.py`)
- Layout engine → Desktop companion: returns layout (evidence: `PC-Companion-App-v4/companion-common/layout_engine.py`)
- Desktop companion → Metrics renderer: sends stats
- Linux companion → Metrics renderer: sends stats
- Metrics renderer → Matrix display: renders metrics
- Clock owner → Weather service: enables weather
- Weather service → Weather provider: fetches forecast
- Audio visualizer → LED strip effects: provides audio levels (evidence: `src/led/led_strip.cpp`)
- Clock owner → Notifications: sends alerts
- Desktop companion → Companion web server: uses companion UI (evidence: `PC-Companion-App-v4/companion-common/server.py`)
- Clock owner → Animation transfer: uploads animation
- Animation transfer → Animation storage: transfers animation
- Wi-Fi and time → Device web API: hosts web service
