# sushimanz/arcade-marquee-manager architecture

> Architecture diagram of the GitHub repository sushimanz/arcade-marquee-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sushimanz/arcade-marquee-manager
- Repository: https://github.com/sushimanz/arcade-marquee-manager

## Overview

1. **What this repo is**  
   This is an **ESP32 firmware project** for driving a **HUB75 LED matrix marquee** and cycling through a set of visual demos/games. It is built as a **PlatformIO / Arduino** project, not a general-purpose application.

2. **Top-level runtime boundary**  
   The firmware entrypoint is `src/main.ino`. That sketch is the orchestration layer: it initializes the display hardware, selects or schedules demos, and runs the active demo logic. There is no separate backend, UI server, or network subsystem in this repo.

3. **Display hardware subsystem**  
   The core hardware dependency is the vendored driver in `lib/MatrixPanelDriver`. It includes `ESP32-HUB75-MatrixPanel-I2S-DMA` plus `Adafruit_GFX`, which together provide the drawing API and the ESP32 I2S/DMA transport to the matrix panels. This is the key boundary between firmware logic and physical LEDs.

4. **Global configuration layer**  
   `src/definitions.h` centralizes board/display constants such as panel resolution, chain size, and shared values used by all demos. The README makes clear this is the place where panel geometry is adapted for different matrix sizes. This file is the main compile-time configuration boundary.

5. **Demo framework architecture**  
   The demos are not standalone sketches; they plug into a common framework under `src/demos/utilities`. That layer defines the demo abstraction and shared helpers, including the patterns for reset, primary loop, and optional exit condition. The main runtime treats each demo as a scheduled unit with a duration and lifecycle callbacks.

6. **Per-demo isolation**  
   Each animation/game lives in its own `.cpp/.h` pair under `src/demos` such as `conway`, `pong`, `snake`, `maze`, `plasma`, and others. Each demo owns its own state and rendering behavior, which keeps game logic isolated from the rest of the system. Shared state is intentionally minimized and, per the README, kept static inside the `.cpp` files.

7. **Rendering/data flow**  
   The basic flow is: **demo logic computes frame state → demo issues draw calls → MatrixPanel driver pushes pixels to the HUB75 panels**. Rendering is direct-to-display; there is no scene graph, compositor, or retained UI layer. The demos use `dma_display` methods like pixel drawing and fill operations to produce frames.

8. **Important architectural constraint: write-only display**  
   The README highlights a major limitation: the display API does **not** provide pixel reads, and it does **not** auto-clear the screen. That means demos must explicitly erase or redraw their content, and any demo that needs previous frame state must maintain its own buffer in memory. This strongly shapes the implementation style of animation and game demos.

9. **Demo lifecycle model**  
   Each demo is scheduled with a **timer-based runtime** and optional lifecycle hooks: reset before start, primary loop during execution, and optional exit condition. That makes the system more like a cooperative demo runner than a preemptive game engine. Timing and termination are managed at the demo-framework level, not inside a centralized scheduler.

10. **Project boundaries and unused areas**  
   `include/` and `test/` are present but marked unused, so the meaningful code path is concentrated in `src/` and `lib/`. `platformio.ini` controls build/upload settings, while the external library folder is the main non-project dependency. There is no evidence of cloud services, storage, or other external runtime infrastructure.

11. **Hardware assumptions**  
   The code is targeted at an **ESP32 driving a 256x64 HUB75 matrix**, often implemented as four 64x64 panels chained horizontally. The architecture assumes side-by-side chaining and a 64-pixel-tall display; support for other geometries exists but is described as less tested. Power, wiring, and the ESP32-to-panel signal path are therefore part of the system boundary.

12. **How to diagram it**  
   A clear architecture diagram would show: **PlatformIO build config → ESP32 firmware (`main.ino`) → demo framework/utilities → individual demo modules → MatrixPanel driver → HUB75 panels**. `definitions.h` should be drawn as a shared configuration input across the firmware, and `lib/MatrixPanelDriver` as the hardware abstraction layer underneath all rendering.

Main entry points: [`src/demos/utilities/demo.h`](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/utilities/demo.h) (Demo core), [`lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h`](https://github.com/sushimanz/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h) (Matrix driver), [`src/definitions.h`](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/definitions.h) (Definitions), [`src/main.ino`](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/main.ino) (Main sketch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware"]
  node_platformio["PlatformIO<br/>build config<br/>[platformio.ini]"]
  node_main["Main sketch<br/>firmware entry<br/>[main.ino]"]
  node_definitions["Definitions<br/>shared config<br/>[definitions.h]"]
  node_demo_core["Demo core<br/>lifecycle API<br/>[demo.h]"]
  node_demo_utils["Demo utils<br/>helpers<br/>[demo_utilities.h]"]
end

subgraph group_demos["Demos"]
  node_conway["Conway<br/>cellular automaton<br/>[conway.h]"]
  node_pong["Pong<br/>game demo<br/>[pong.h]"]
  node_snake["Snake<br/>game demo<br/>[snake.h]"]
  node_maze["Maze<br/>path demo<br/>[maze.h]"]
  node_plasma["Plasma<br/>visual demo<br/>[plasma.h]"]
  node_discoball["Disco ball<br/>visual demo<br/>[discoball.h]"]
  node_other_demos["Other demos<br/>demo bundle"]
end

subgraph group_displaylib["Display Lib"]
  node_matrix_driver["Matrix driver<br/>display driver"]
  node_gfx["Adafruit GFX<br/>draw API<br/>[Adafruit_GFX.h]"]
  node_dma["DMA transport<br/>i2s dma backend"]
  node_hub75[("HUB75 panels<br/>physical display")]
end

node_platformio -->|"builds"| node_main
node_definitions -->|"configures"| node_main
node_definitions -->|"feeds"| node_demo_core
node_definitions -->|"feeds"| node_conway
node_definitions -->|"feeds"| node_pong
node_definitions -->|"feeds"| node_snake
node_definitions -->|"feeds"| node_maze
node_definitions -->|"feeds"| node_plasma
node_definitions -->|"feeds"| node_discoball
node_main -->|"orchestrates"| node_demo_core
node_main -->|"initializes"| node_matrix_driver
node_demo_core -->|"uses"| node_demo_utils
node_demo_core -->|"runs"| node_conway
node_demo_core -->|"runs"| node_pong
node_demo_core -->|"runs"| node_snake
node_demo_core -->|"runs"| node_maze
node_demo_core -->|"runs"| node_plasma
node_demo_core -->|"runs"| node_discoball
node_demo_core -->|"runs"| node_other_demos
node_conway -->|"draws to"| node_matrix_driver
node_pong -->|"draws to"| node_matrix_driver
node_snake -->|"draws to"| node_matrix_driver
node_maze -->|"draws to"| node_matrix_driver
node_plasma -->|"draws to"| node_matrix_driver
node_discoball -->|"draws to"| node_matrix_driver
node_other_demos -->|"draws to"| node_matrix_driver
node_matrix_driver -->|"uses"| node_gfx
node_matrix_driver -->|"drives"| node_dma
node_dma -->|"refreshes"| node_hub75
node_gfx -->|"renders"| node_hub75

click node_platformio "https://github.com/sushimanz/arcade-marquee-manager/blob/main/platformio.ini"
click node_main "https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/main.ino"
click node_definitions "https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/definitions.h"
click node_demo_core "https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/utilities/demo.h"
click node_demo_utils "https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/utilities/demo_utilities.h"
click node_conway "https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/conway.h"
click node_pong "https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/pong.h"
click node_snake "https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/snake.h"
click node_maze "https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/maze.h"
click node_plasma "https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/plasma.h"
click node_discoball "https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/discoball.h"
click node_matrix_driver "https://github.com/sushimanz/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h"
click node_gfx "https://github.com/sushimanz/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/Adafruit_GFX.h"
click node_dma "https://github.com/sushimanz/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/esp32_i2s_parallel_dma.h"

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_platformio,node_main,node_definitions,node_demo_core,node_demo_utils toneBlue
class node_conway,node_pong,node_snake,node_maze,node_plasma,node_discoball,node_other_demos toneAmber
class node_matrix_driver,node_gfx,node_dma,node_hub75 toneMint
```

## Components

### Firmware

PlatformIO-managed ESP32 application code.

- [PlatformIO](https://github.com/sushimanz/arcade-marquee-manager/blob/main/platformio.ini): build config · Build, upload, and environment settings. · `platformio.ini`
- [Main sketch](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/main.ino): firmware entry · ESP32 runtime orchestrator for display setup and demo execution. · `src/main.ino`
- [Definitions](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/definitions.h): shared config · Central geometry and firmware constants. · `src/definitions.h`
- [Demo core](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/utilities/demo.h): lifecycle API · Common demo abstraction and scheduling hooks. · `src/demos/utilities/demo.h`
- [Demo utils](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/utilities/demo_utilities.h): helpers · Shared demo support routines and timing helpers. · `src/demos/utilities/demo_utilities.h`

### Demos

Individual marquee animations and games.

- [Conway](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/conway.h): cellular automaton · Game of Life style demo. · `src/demos/conway.h`
- [Pong](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/pong.h): game demo · Ball-and-paddle demo. · `src/demos/pong.h`
- [Snake](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/snake.h): game demo · Grid-based snake game demo. · `src/demos/snake.h`
- [Maze](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/maze.h): path demo · Maze generation and traversal demo. · `src/demos/maze.h`
- [Plasma](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/plasma.h): visual demo · Procedural color field animation. · `src/demos/plasma.h`
- [Disco ball](https://github.com/sushimanz/arcade-marquee-manager/blob/main/src/demos/discoball.h): visual demo · Animated light effect demo. · `src/demos/discoball.h`
- **Other demos**: demo bundle · Additional marquee demos such as IEEE, UB, linerocker, and paintrollers.

### Display Lib

Vendored HUB75 drawing and transport stack.

- [Matrix driver](https://github.com/sushimanz/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h): display driver · HUB75 panel drawing API and ESP32 panel control. · `lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h`
- [Adafruit GFX](https://github.com/sushimanz/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/Adafruit_GFX.h): draw API · 2D drawing primitives used by demos and the driver. · `lib/MatrixPanelDriver/src/Adafruit_GFX.h`
- [DMA transport](https://github.com/sushimanz/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/esp32_i2s_parallel_dma.h): i2s dma backend · Low-level ESP32 parallel output engine for panel refresh. · `lib/MatrixPanelDriver/src/esp32_i2s_parallel_dma.h`
- **HUB75 panels**: physical display · Chained LED matrix hardware driven by the ESP32.

## Connections

- PlatformIO → Main sketch: builds · PlatformIO compiles and uploads the firmware entrypoint.
- Definitions → Main sketch: configures · Shared geometry and constants shape startup and scheduling.
- Definitions → Demo core: feeds · Common constants are consumed by the demo framework.
- Definitions → Conway: feeds · Demo geometry and limits depend on shared definitions.
- Definitions → Pong: feeds · Demo geometry and limits depend on shared definitions.
- Definitions → Snake: feeds · Demo geometry and limits depend on shared definitions.
- Definitions → Maze: feeds · Demo geometry and limits depend on shared definitions.
- Definitions → Plasma: feeds · Demo geometry and limits depend on shared definitions.
- Definitions → Disco ball: feeds · Demo geometry and limits depend on shared definitions.
- Main sketch → Demo core: orchestrates · The sketch selects demos and advances their lifecycle.
- Main sketch → Matrix driver: initializes · Firmware sets up the display hardware boundary.
- Demo core → Demo utils: uses · Lifecycle logic relies on shared helper routines.
- Demo core → Conway: runs · The framework executes the Conway demo as a scheduled unit.
- Demo core → Pong: runs · The framework executes the Pong demo as a scheduled unit.
- Demo core → Snake: runs · The framework executes the Snake demo as a scheduled unit.
- Demo core → Maze: runs · The framework executes the Maze demo as a scheduled unit.
- Demo core → Plasma: runs · The framework executes the Plasma demo as a scheduled unit.
- Demo core → Disco ball: runs · The framework executes the Disco ball demo as a scheduled unit.
- Demo core → Other demos: runs · Additional demos plug into the same lifecycle model.
- Conway → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Pong → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Snake → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Maze → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Plasma → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Disco ball → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Other demos → Matrix driver: draws to · Remaining demos use the same direct rendering path.
- Matrix driver → Adafruit GFX: uses · The matrix driver exposes Adafruit GFX drawing primitives.
- Matrix driver → DMA transport: drives · The driver pushes pixels through the ESP32 DMA backend.
- DMA transport → HUB75 panels: refreshes · Parallel I2S/DMA output updates the physical LED panels.
- Adafruit GFX → HUB75 panels: renders · Drawing primitives ultimately target the hardware display.
