# blueforcer/awtrix3 architecture

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

- Interactive diagram: https://gitdiagram.com/blueforcer/awtrix3
- Repository: https://github.com/blueforcer/awtrix3

## Overview

1. **Repository shape**
   - This repo is primarily an **ESP32 firmware project** for AWTRIX 3, a programmable LED matrix clock/display.
   - It also contains **host-side tooling**: documentation, web-flasher assets, helper conversion scripts, and a separate **AWL_Backup** desktop utility.

2. **Core runtime boundary**
   - The embedded application lives under `src/` and is built with **PlatformIO / Arduino-style C++** for ESP32.
   - `src/main.cpp` is the entry point and wires together the major managers and services that run on the device.

3. **Display/content pipeline**
   - The firmware’s central job is to turn a stream of content into pixels on the matrix.
   - `Apps`, `Dictionary`, `DisplayManager`, `MatrixDisplayUi`, `Overlays`, `effects`, and `icons` form the rendering/content layer.
   - This layer handles built-in clock/status pages, custom app payloads, overlays, animated icons, and visual effects.

4. **External input sources**
   - Content and commands can arrive through **MQTT** and **HTTP** APIs, which are the main integration points called out in the README.
   - `MQTTManager` and `ServerManager` are the primary protocol gateways.
   - The repo also includes `ArtnetWifi`, which suggests a networked light/control input path separate from the normal app feed.

5. **Local web and file services**
   - `lib/webserver` and `ServerManager` indicate an embedded web UI plus file-management functionality on the device.
   - The README explicitly mentions an **integrated file browser** and **onscreen settings menu**; these are separate from the external API path and give direct local control.

6. **Device management and state**
   - `Globals`, `Functions`, `PowerManager`, `PeripheryManager`, and `UpdateManager` handle cross-cutting device behavior.
   - These modules likely manage boot/runtime state, power behavior, attached hardware, and firmware update flows.
   - `cert.h` indicates HTTPS/TLS-related support is embedded where needed.

7. **User interaction and system UI**
   - `MenuManager` and `timer` support local interactions and scheduled behavior.
   - The built-in UI is not just a display output; it is also a device settings surface for adjusting firmware behavior directly on the clock.

8. **Built-in features beyond the clock**
   - `Games/` contains interactive mini-games such as `AwtrixSays` and `SlotMachine`, coordinated by `GameManager`.
   - `MelodyPlayer/` provides RTTTL-style sound playback, and `GifPlayer.h` plus media/icon assets support richer visual content.

9. **Hardware and integration libraries**
   - `lib/home-assistant-integration` is a full Arduino library for **Home Assistant MQTT discovery and device modeling**.
   - Other bundled libraries support display/media and peripherals: `TJpg_Decoder`, `DFMiniMp3`, `MeanFilterLib`, `MedianFilterLib`, `LightResistor`, and `webserver`.
   - These libraries are part of the firmware’s device-side dependency boundary, not separate services.

10. **Host-side tooling and asset pipeline**
   - `Helper_Scripts/` contains Go/Python utilities for image conversion, screenshots, and AWTRIX cloning workflows; these are build-time or content-prep tools, not firmware runtime code.
   - `docs/` is the public documentation site and also hosts **online flasher** bundles for different targets.
   - `AWL_Backup/` is a separate **B4J desktop application** packaged with a built executable, used for backup-related device management.

11. **Deployment and target profile**
   - The firmware is explicitly **ESP32-only** and has board/configuration support for an ESP32-S3 target in `boards/`.
   - The repository includes prebuilt binaries and web-flasher packages under `docs/*_flasher/`, showing that distribution is designed around both source builds and end-user flashing.

12. **High-level architecture summary**
   - At a diagram level, the system is: **external controllers/home automation systems → MQTT/HTTP/Artnet gateways → app/state managers → display/effects/rendering pipeline → ESP32 hardware peripherals and LED matrix**.
   - Local user control and maintenance run in parallel through the **onscreen menu**, **web UI/file browser**, and **update/backup tooling**.

Main entry points: [`src/main.cpp`](https://github.com/blueforcer/awtrix3/blob/main/src/main.cpp) (Main), [`src/DisplayManager.h`](https://github.com/blueforcer/awtrix3/blob/main/src/DisplayManager.h) (Display), [`src/Apps.h`](https://github.com/blueforcer/awtrix3/blob/main/src/Apps.h) (Apps), [`docs/index.html`](https://github.com/blueforcer/awtrix3/blob/main/docs/index.html) (Docs site)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["ESP32 firmware"]
  node_main["Main<br/>firmware entry<br/>[main.cpp]"]
  node_globals["Globals<br/>runtime state<br/>[Globals.h]"]
  node_functions["Functions<br/>core helpers<br/>[Functions.h]"]
  node_mqtt["MQTT<br/>protocol gateway<br/>[MQTTManager.h]"]
  node_server["Server<br/>http/web gateway<br/>[ServerManager.h]"]
  node_artnet["Artnet<br/>light input<br/>[ArtnetWifi.h]"]
  node_apps["Apps<br/>[Apps.h]"]
  node_dictionary["Dictionary<br/>content rules<br/>[Dictionary.h]"]
  node_display["Display<br/>render manager<br/>[DisplayManager.h]"]
  node_ui["UI<br/>[MatrixDisplayUi.h]"]
  node_overlays["Overlays<br/>render layer<br/>[Overlays.h]"]
  node_effects["Effects<br/>animation layer<br/>[effects.h]"]
  node_icons["Icons<br/>asset layer<br/>[icons.h]"]
  node_menu["Menu<br/>local control<br/>[MenuManager.h]"]
  node_power["Power<br/>device control<br/>[PowerManager.h]"]
  node_periphery["Periphery<br/>hardware control<br/>[PeripheryManager.h]"]
  node_update["Update<br/>maintenance<br/>[UpdateManager.h]"]
  node_games["Games<br/>interactive features<br/>[GameManager.h]"]
  node_melody["Melody<br/>sound playback<br/>[melody_player.h]"]
end

subgraph group_device_libs["Bundled device libs"]
  node_webserverlib["Webserver lib<br/>embedded library<br/>[esp-fs-webserver.h]"]
  node_haintegration["HA MQTT<br/>embedded library<br/>[HAMqtt.h]"]
end

subgraph group_host["Host tooling"]
  node_helpers["Helper scripts<br/>host tooling<br/>[Awtrix_Clone.go]"]
  node_backupapp["AWL Backup<br/>desktop utility<br/>[AWL-Backup.b4j]"]
end

subgraph group_docs["Docs and distribution"]
  node_docs_site["Docs site<br/>documentation<br/>[index.html]"]
end

node_main -->|"init"| node_globals
node_main -->|"uses"| node_functions
node_main -->|"starts"| node_mqtt
node_main -->|"starts"| node_server
node_main -->|"starts"| node_artnet
node_main -->|"loads"| node_apps
node_main -->|"starts"| node_display
node_main -->|"starts"| node_menu
node_main -->|"starts"| node_power
node_main -->|"starts"| node_periphery
node_main -->|"starts"| node_update
node_display -->|"drives"| node_ui
node_display -->|"composes"| node_overlays
node_display -->|"applies"| node_effects
node_display -->|"uses"| node_icons
node_apps -->|"uses"| node_dictionary
node_apps -->|"includes"| node_games
node_apps -->|"uses"| node_melody
node_mqtt -->|"integrates"| node_haintegration
node_server -->|"built on"| node_webserverlib
node_helpers -->|"feeds"| node_docs_site
node_backupapp -->|"described by"| node_docs_site
node_update -->|"published in"| node_docs_site

click node_main "https://github.com/blueforcer/awtrix3/blob/main/src/main.cpp"
click node_globals "https://github.com/blueforcer/awtrix3/blob/main/src/Globals.h"
click node_functions "https://github.com/blueforcer/awtrix3/blob/main/src/Functions.h"
click node_mqtt "https://github.com/blueforcer/awtrix3/blob/main/src/MQTTManager.h"
click node_server "https://github.com/blueforcer/awtrix3/blob/main/src/ServerManager.h"
click node_artnet "https://github.com/blueforcer/awtrix3/blob/main/src/ArtnetWifi.h"
click node_apps "https://github.com/blueforcer/awtrix3/blob/main/src/Apps.h"
click node_dictionary "https://github.com/blueforcer/awtrix3/blob/main/src/Dictionary.h"
click node_display "https://github.com/blueforcer/awtrix3/blob/main/src/DisplayManager.h"
click node_ui "https://github.com/blueforcer/awtrix3/blob/main/src/MatrixDisplayUi.h"
click node_overlays "https://github.com/blueforcer/awtrix3/blob/main/src/Overlays.h"
click node_effects "https://github.com/blueforcer/awtrix3/blob/main/src/effects.h"
click node_icons "https://github.com/blueforcer/awtrix3/blob/main/src/icons.h"
click node_menu "https://github.com/blueforcer/awtrix3/blob/main/src/MenuManager.h"
click node_power "https://github.com/blueforcer/awtrix3/blob/main/src/PowerManager.h"
click node_periphery "https://github.com/blueforcer/awtrix3/blob/main/src/PeripheryManager.h"
click node_update "https://github.com/blueforcer/awtrix3/blob/main/src/UpdateManager.h"
click node_games "https://github.com/blueforcer/awtrix3/blob/main/src/Games/GameManager.h"
click node_melody "https://github.com/blueforcer/awtrix3/blob/main/src/MelodyPlayer/melody_player.h"
click node_webserverlib "https://github.com/blueforcer/awtrix3/blob/main/lib/webserver/esp-fs-webserver.h"
click node_haintegration "https://github.com/blueforcer/awtrix3/blob/main/lib/home-assistant-integration/src/HAMqtt.h"
click node_helpers "https://github.com/blueforcer/awtrix3/blob/main/Helper_Scripts/Awtrix_Clone.go"
click node_backupapp "https://github.com/blueforcer/awtrix3/blob/main/AWL_Backup/AWL-Backup.b4j"
click node_docs_site "https://github.com/blueforcer/awtrix3/blob/main/docs/index.html"

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_globals,node_functions,node_mqtt,node_server,node_artnet,node_apps,node_dictionary,node_display,node_ui,node_overlays,node_effects,node_icons,node_menu,node_power,node_periphery,node_update,node_games,node_melody toneBlue
class node_webserverlib,node_haintegration toneAmber
class node_helpers,node_backupapp toneMint
class node_docs_site toneRose
```

## Components

### ESP32 firmware

Device-side runtime built for the AWTRIX display on ESP32.

- [Main](https://github.com/blueforcer/awtrix3/blob/main/src/main.cpp): firmware entry · Bootstraps the embedded application and wires the device managers. · `src/main.cpp`
- [Globals](https://github.com/blueforcer/awtrix3/blob/main/src/Globals.h): runtime state · Shared device state and cross-cutting configuration. · `src/Globals.h`
- [Functions](https://github.com/blueforcer/awtrix3/blob/main/src/Functions.h): core helpers · Common firmware routines used across subsystems. · `src/Functions.h`
- [MQTT](https://github.com/blueforcer/awtrix3/blob/main/src/MQTTManager.h): protocol gateway · MQTT command and content ingress from external controllers. · `src/MQTTManager.h`
- [Server](https://github.com/blueforcer/awtrix3/blob/main/src/ServerManager.h): http/web gateway · Embedded HTTP server, file browser, and local web UI surface. · `src/ServerManager.h`
- [Artnet](https://github.com/blueforcer/awtrix3/blob/main/src/ArtnetWifi.h): light input · Networked lighting/control input path separate from MQTT. · `src/ArtnetWifi.h`
- [Apps](https://github.com/blueforcer/awtrix3/blob/main/src/Apps.h): content apps · Built-in app model and payload handling for display content. · `src/Apps.h`
- [Dictionary](https://github.com/blueforcer/awtrix3/blob/main/src/Dictionary.h): content rules · Text, token, and content lookup support for rendering. · `src/Dictionary.h`
- [Display](https://github.com/blueforcer/awtrix3/blob/main/src/DisplayManager.h): render manager · Coordinates matrix output and visual composition. · `src/DisplayManager.h`
- [UI](https://github.com/blueforcer/awtrix3/blob/main/src/MatrixDisplayUi.h): screen ui · On-device display UI and page navigation. · `src/MatrixDisplayUi.h`
- [Overlays](https://github.com/blueforcer/awtrix3/blob/main/src/Overlays.h): render layer · Status and temporary overlay graphics drawn over content. · `src/Overlays.h`
- [Effects](https://github.com/blueforcer/awtrix3/blob/main/src/effects.h): animation layer · Visual effects used by the matrix display pipeline. · `src/effects.h`
- [Icons](https://github.com/blueforcer/awtrix3/blob/main/src/icons.h): asset layer · Icon drawing and embedded visual assets. · `src/icons.h`
- [Menu](https://github.com/blueforcer/awtrix3/blob/main/src/MenuManager.h): local control · Onscreen settings menu and direct user interaction. · `src/MenuManager.h`
- [Power](https://github.com/blueforcer/awtrix3/blob/main/src/PowerManager.h): device control · Power behavior, brightness, and device lifecycle control. · `src/PowerManager.h`
- [Periphery](https://github.com/blueforcer/awtrix3/blob/main/src/PeripheryManager.h): hardware control · Attached hardware and peripheral management. · `src/PeripheryManager.h`
- [Update](https://github.com/blueforcer/awtrix3/blob/main/src/UpdateManager.h): maintenance · Firmware update and maintenance workflow. · `src/UpdateManager.h`
- [Games](https://github.com/blueforcer/awtrix3/blob/main/src/Games/GameManager.h): interactive features · Mini-games and game coordination for the device. · `src/Games/GameManager.h`
- [Melody](https://github.com/blueforcer/awtrix3/blob/main/src/MelodyPlayer/melody_player.h): sound playback · RTTTL-style melody playback and note generation. · `src/MelodyPlayer/melody_player.h`

### Bundled device libs

Embedded libraries and support modules shipped with the firmware.

- [Webserver lib](https://github.com/blueforcer/awtrix3/blob/main/lib/webserver/esp-fs-webserver.h): embedded library · Bundled filesystem web server implementation used by the device UI. · `lib/webserver/esp-fs-webserver.h`
- [HA MQTT](https://github.com/blueforcer/awtrix3/blob/main/lib/home-assistant-integration/src/HAMqtt.h): embedded library · Home Assistant discovery and MQTT device modeling library. · `lib/home-assistant-integration/src/HAMqtt.h`

### Host tooling

Desktop and build-time tools used for conversion, flashing, and backup.

- [Helper scripts](https://github.com/blueforcer/awtrix3/blob/main/Helper_Scripts/Awtrix_Clone.go): host tooling · Go and Python utilities for image conversion, cloning, and screenshots. · `Helper_Scripts/Awtrix_Clone.go`
- [AWL Backup](https://github.com/blueforcer/awtrix3/blob/main/AWL_Backup/AWL-Backup.b4j): desktop utility · Separate desktop application for backup-related device management. · `AWL_Backup/AWL-Backup.b4j`

### Docs and distribution

Documentation site and prebuilt flashing bundles.

- [Docs site](https://github.com/blueforcer/awtrix3/blob/main/docs/index.html): documentation · Public documentation and web-flasher distribution site. · `docs/index.html`

## Connections

- Main → Globals: init · Boot sequence initializes shared runtime state.
- Main → Functions: uses · Main runtime relies on shared helper routines.
- Main → MQTT: starts · Entry point wires the MQTT gateway.
- Main → Server: starts · Entry point wires the embedded web/file server.
- Main → Artnet: starts · Entry point enables Artnet input handling.
- Main → Apps: loads · Entry point registers content apps and runtime pages.
- Main → Display: starts · Entry point initializes the display pipeline.
- Main → Menu: starts · Entry point enables local menu control.
- Main → Power: starts · Entry point configures power management.
- Main → Periphery: starts · Entry point configures attached hardware.
- Main → Update: starts · Entry point enables update handling.
- Display → UI: drives · Display manager presents the matrix UI and pages.
- Display → Overlays: composes · Overlay layer is composited into rendered frames.
- Display → Effects: applies · Visual effects are applied during rendering.
- Display → Icons: uses · Icon assets feed the render pipeline.
- Apps → Dictionary: uses · App content relies on lookup and text mapping support.
- Apps → Games: includes · Game subsystem is exposed as part of built-in apps.
- Apps → Melody: uses · Apps can trigger sound playback.
- MQTT → HA MQTT: integrates · MQTT path supports Home Assistant discovery and device models.
- Server → Webserver lib: built on · Device web interface is powered by the bundled webserver library.
- Helper scripts → Docs site: feeds · Host utilities support content prep and documentation workflows.
- AWL Backup → Docs site: described by · Desktop backup utility is documented alongside flashing and maintenance.
- Update → Docs site: published in · Firmware update and flashing flows are distributed through docs.
