# ubieee/arcade-marquee-manager architecture

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

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

## Overview

1. **What this repository is**
   - This is a PlatformIO-based **ESP32 firmware project** for driving a **HUB75 LED matrix marquee** and cycling through a set of visual demos/games.
   - It is not a conventional app with request/response flow; the architecture is a **single embedded runtime** that continuously renders to the matrix panel hardware.

2. **Top-level split: app code vs. vendored display library**
   - The repository has two main code boundaries:
     - `src/` contains the project’s own firmware logic and all demos.
     - `lib/MatrixPanelDriver/` contains a vendored ESP32 HUB75 DMA display library plus its bundled Adafruit GFX dependency.
   - The app code depends on that library for all panel I/O, pixel drawing, text, and DMA-driven refresh.

3. **Runtime entry point and orchestration**
   - `src/main.ino` is the application entry point and likely owns the ESP32 Arduino lifecycle (`setup`/`loop`).
   - The main loop’s job is to initialize the display, select or advance demos, and call the currently active demo function(s) repeatedly.
   - The README implies demos are selected from a central registry rather than discovered dynamically.

4. **Demo framework as the core application subsystem**
   - `src/demos/utilities/demo.h` and `demo.cpp` appear to define the **demo abstraction** used throughout the project.
   - Each demo is represented by a `Demo` struct containing:
     - the main render/update function,
     - a runtime duration,
     - an optional reset function,
     - an optional exit-condition function.
   - This makes the system **time-sliced and function-pointer driven**, with the framework managing when a demo starts, runs, and exits.

5. **Demo registry and lifecycle**
   - The README describes a vector of `Demo` entries in `demo.cpp`, meaning the active demo list is centralized there.
   - Lifecycle is:
     - optional reset,
     - repeated primary loop execution,
     - optional exit check before each iteration,
     - automatic termination when the configured time elapses.
   - This is the main control-flow boundary in the project: demos do not own the full program, they are scheduled by the demo manager.

6. **Individual demo modules**
   - `src/demos/` contains the actual visual/program demos:
     - `IEEE`, `UB`, `discoball`, `linerocker`, `maze`, `paintrollers`, `plasma`, `pong`, `snake`, `conway`.
   - Each demo is split into a `.cpp` and `.h` pair and is expected to expose no-parameter functions that the registry can call.
   - Some demos are simple animation loops; others are interactive or stateful mini-games.

7. **Shared demo utilities**
   - `src/demos/utilities/` holds common code reused by multiple demos.
   - Based on the README and file names, this layer likely includes the `Demo` struct definition, common demo helpers, and shared timing/state helpers.
   - This prevents each demo from reimplementing its own scheduling or boilerplate.

8. **Hardware abstraction and global display access**
   - Demos talk to the panel through a shared global display object, referenced in the README as `dma_display` of type `MatrixPanel_I2S_DMA`.
   - The display library boundary is important:
     - demos call methods such as pixel drawing, fills, text, and color conversion,
     - the library handles HUB75 signaling and DMA refresh on ESP32.
   - The project uses **global externs** for hardware access and colors, which keeps demo signatures simple but couples demos to the display runtime.

9. **Configuration and display geometry**
   - `src/definitions.h` is the central configuration file for panel dimensions and other shared constants.
   - The README highlights that the code assumes a **left-to-right chained panel layout** and uses values like `PANEL_TOTAL_X`, `PANEL_RES_Y`, `PANEL_RES_X`, and `PANEL_CHAIN`.
   - This file is the architectural boundary for hardware portability: changing panel geometry is meant to happen here, not inside each demo.

10. **Rendering model and state handling**
   - The architecture is immediate-mode drawing against a hardware-backed framebuffer-like interface, but with an important limitation: there is no built-in `getPixel`.
   - As a result, demos that need simulation state over time must maintain their own buffers or internal state, as seen in the README’s reference to `conway.cpp`.
   - This means the project mixes:
     - pure animation demos that redraw every frame,
     - stateful simulations that track their own world model.

11. **Build and deployment environment**
   - The project is built with **PlatformIO** and deployed to an **ESP32**.
   - The external runtime environment matters architecturally because the code is compiled as Arduino-style embedded firmware, not desktop software.
   - Serial monitoring and upload are part of the operational workflow, but the core runtime remains device-local once flashed.

12. **Non-active folders and project boundaries**
   - `include/` and `test/` are present but marked unutilized in the README, so they do not currently participate in the architecture.
   - This reinforces that the live system is concentrated in `src/` plus the vendored matrix driver under `lib/`.

13. **How to think about the system diagram**
   - The clean architecture view is:
     - **ESP32 firmware runtime** at the center,
     - **demo scheduler** dispatching into one of many demo modules,
     - **shared utilities/config** providing constants and demo scaffolding,
     - **display driver library** as the hardware I/O boundary,
     - **HUB75 matrix panels** as the external physical output device.
   - The main data flow is one-way: demo logic generates visual state and pushes it into the display driver, which streams it to the LED matrix.

Main entry points: [`lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h`](https://github.com/ubieee/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h) (Matrix driver), [`src/demos/utilities/demo.cpp`](https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/utilities/demo.cpp) (Demo manager), [`src/definitions.h`](https://github.com/ubieee/arcade-marquee-manager/blob/main/src/definitions.h) (Display config), [`src/demos`](https://github.com/ubieee/arcade-marquee-manager/tree/main/src/demos) (Animations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Firmware"]
  node_main["Main loop<br/>Arduino entrypoint<br/>[main.ino]"]
  node_config["Display config<br/>panel constants<br/>[definitions.h]"]
  node_demo_contract["Demo API<br/>demo struct<br/>[demo.h]"]
  node_demo_mgr["Demo manager<br/>scheduler<br/>[demo.cpp]"]
  node_demo_utils_h["Demo helpers<br/>shared utilities<br/>[demo_utilities.h]"]
  node_demo_utils_cpp["Helper impl<br/>shared utilities<br/>[demo_utilities.cpp]"]
  node_anim_demos["Animations<br/>demo set"]
  node_game_demos["Games<br/>demo set"]
  node_sim_demo["Conway<br/>simulation demo<br/>[conway.cpp]"]
end

subgraph group_vendor["Display Library"]
  node_display_api["Matrix driver<br/>HUB75 DMA library"]
  node_gfx["GFX layer<br/>graphics dep<br/>[Adafruit_GFX.h]"]
  node_virtual_panel["Virtual panel<br/>panel mapping"]
  node_dma_engine["DMA engine<br/>refresh backend"]
end

subgraph group_device["Hardware"]
  node_led_matrix[("LED matrix<br/>HUB75 panels")]
end

node_main -->|"reads"| node_config
node_main -->|"runs"| node_demo_mgr
node_demo_mgr -->|"uses"| node_demo_contract
node_demo_mgr -->|"calls"| node_demo_utils_h
node_demo_utils_h -->|"implemented by"| node_demo_utils_cpp
node_demo_mgr -->|"dispatches"| node_anim_demos
node_demo_mgr -->|"dispatches"| node_game_demos
node_demo_mgr -->|"dispatches"| node_sim_demo
node_anim_demos -->|"draws via"| node_display_api
node_game_demos -->|"draws via"| node_display_api
node_sim_demo -->|"draws via"| node_display_api
node_anim_demos -->|"uses"| node_config
node_game_demos -->|"uses"| node_config
node_sim_demo -->|"uses"| node_config
node_display_api -->|"wraps"| node_gfx
node_display_api -->|"maps"| node_virtual_panel
node_display_api -->|"refreshes with"| node_dma_engine
node_dma_engine -->|"drives"| node_led_matrix
node_virtual_panel -->|"targets"| node_led_matrix
node_demo_utils_cpp -->|"supports"| node_display_api

click node_main "https://github.com/ubieee/arcade-marquee-manager/blob/main/src/main.ino"
click node_config "https://github.com/ubieee/arcade-marquee-manager/blob/main/src/definitions.h"
click node_demo_contract "https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/utilities/demo.h"
click node_demo_mgr "https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/utilities/demo.cpp"
click node_demo_utils_h "https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/utilities/demo_utilities.h"
click node_demo_utils_cpp "https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/utilities/demo_utilities.cpp"
click node_anim_demos "https://github.com/ubieee/arcade-marquee-manager/tree/main/src/demos"
click node_game_demos "https://github.com/ubieee/arcade-marquee-manager/tree/main/src/demos"
click node_sim_demo "https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/conway.cpp"
click node_display_api "https://github.com/ubieee/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h"
click node_gfx "https://github.com/ubieee/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/Adafruit_GFX.h"
click node_virtual_panel "https://github.com/ubieee/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/ESP32-VirtualMatrixPanel-I2S-DMA.h"
click node_dma_engine "https://github.com/ubieee/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_main,node_config,node_demo_contract,node_demo_mgr,node_demo_utils_h,node_demo_utils_cpp,node_anim_demos,node_game_demos,node_sim_demo toneBlue
class node_display_api,node_gfx,node_virtual_panel,node_dma_engine toneAmber
class node_led_matrix toneMint
```

## Components

### Firmware

Project-owned ESP32 Arduino firmware and demo logic

- [Main loop](https://github.com/ubieee/arcade-marquee-manager/blob/main/src/main.ino): Arduino entrypoint · ESP32 setup/loop orchestration for the marquee runtime · `src/main.ino`
- [Display config](https://github.com/ubieee/arcade-marquee-manager/blob/main/src/definitions.h): panel constants · Shared geometry and hardware constants for the chained matrix layout · `src/definitions.h`
- [Demo API](https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/utilities/demo.h): demo struct · Function-pointer based demo abstraction with timing and lifecycle hooks · `src/demos/utilities/demo.h`
- [Demo manager](https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/utilities/demo.cpp): scheduler · Central registry and lifecycle control for the active demo sequence · `src/demos/utilities/demo.cpp`
- [Demo helpers](https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/utilities/demo_utilities.h): shared utilities · Common helper declarations reused by multiple demos · `src/demos/utilities/demo_utilities.h`
- [Helper impl](https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/utilities/demo_utilities.cpp): shared utilities · Shared demo support routines and utility implementations · `src/demos/utilities/demo_utilities.cpp`
- [Animations](https://github.com/ubieee/arcade-marquee-manager/tree/main/src/demos): demo set · Visual demo modules such as IEEE, UB, discoball, linerocker, plasma, and paintrollers · `src/demos`
- [Games](https://github.com/ubieee/arcade-marquee-manager/tree/main/src/demos): demo set · Interactive/stateful demos such as maze, pong, and snake · `src/demos`
- [Conway](https://github.com/ubieee/arcade-marquee-manager/blob/main/src/demos/conway.cpp): simulation demo · Stateful cellular automaton demo that maintains its own world state · `src/demos/conway.cpp`

### Display Library

Vendored HUB75 DMA display stack and bundled graphics dependency

- [Matrix driver](https://github.com/ubieee/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h): HUB75 DMA library · ESP32 HUB75 panel driver used for drawing, text, and DMA refresh · `lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h`
- [GFX layer](https://github.com/ubieee/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/Adafruit_GFX.h): graphics dep · Bundled Adafruit GFX compatibility layer used by the display driver · `lib/MatrixPanelDriver/src/Adafruit_GFX.h`
- [Virtual panel](https://github.com/ubieee/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/ESP32-VirtualMatrixPanel-I2S-DMA.h): panel mapping · Panel mapping abstraction for chained matrix layouts · `lib/MatrixPanelDriver/src/ESP32-VirtualMatrixPanel-I2S-DMA.h`
- [DMA engine](https://github.com/ubieee/arcade-marquee-manager/blob/main/lib/MatrixPanelDriver/src/esp32_i2s_parallel_dma.h): refresh backend · Low-level I2S parallel DMA implementation for continuous LED refresh · `lib/MatrixPanelDriver/src/esp32_i2s_parallel_dma.h`

### Hardware

Physical LED matrix output device

- **LED matrix**: HUB75 panels · Physical chained HUB75 LED matrix marquee output

## Connections

- Main loop → Display config: reads · Uses shared panel geometry and constants
- Main loop → Demo manager: runs · Initializes the system and drives demo execution
- Demo manager → Demo API: uses · Schedules demos through the common demo interface
- Demo manager → Demo helpers: calls · Depends on shared helper declarations
- Demo helpers → Helper impl: implemented by · Helper declarations are defined in the utility implementation
- Demo manager → Animations: dispatches · Selects and advances visual animation demos
- Demo manager → Games: dispatches · Selects and advances interactive game demos
- Demo manager → Conway: dispatches · Schedules the Conway simulation demo
- Animations → Matrix driver: draws via · Renders frames through the shared matrix display object
- Games → Matrix driver: draws via · Uses the display driver for pixels, text, and clears
- Conway → Matrix driver: draws via · Pushes simulation output to the hardware display
- Animations → Display config: uses · Relies on panel geometry and color constants
- Games → Display config: uses · Relies on panel geometry and color constants
- Conway → Display config: uses · Relies on panel geometry and color constants
- Matrix driver → GFX layer: wraps · Builds on the bundled Adafruit GFX layer
- Matrix driver → Virtual panel: maps · Supports chained panel addressing and layout mapping
- Matrix driver → DMA engine: refreshes with · Streams frame data through the DMA backend
- DMA engine → LED matrix: drives · Outputs HUB75 signals to the physical matrix panels
- Virtual panel → LED matrix: targets · Describes the chained physical panel arrangement
- Helper impl → Matrix driver: supports · Provides shared drawing or runtime helpers that assume the display API
