# jinglemansweep/wideboy architecture

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

- Interactive diagram: https://gitdiagram.com/jinglemansweep/wideboy
- Repository: https://github.com/jinglemansweep/wideboy

## Overview

##### Main Components
- WideBoy Application: At the center is the “wideboy” package. This is the main entry point (via __main__.py) and includes core modules:
– Components (wideboy/components.py): Likely manage high-level functional pieces.
– Configuration (wideboy/config.py, settings.yml): Uses Dynaconf for flexible settings via TOML and environment variables.
– Core Systems and Engine: Under wideboy/systems, you have modules for display, animation, scene management, drawing functions, and integration with Home Assistant and MQTT.
– Sprites: The wideboy/sprites directory holds various sprite types (animation, text, image carousels, tile grids) that represent visual components on the LED matrix.
- Scene Management: The scenes folder (e.g., scenes/default.yml) indicates that there is a scene system where different visual “scenes” or configurations can be set up.
- Home Assistant and MQTT Integration:
– The README explains deep MQTT integration, including MQTT Discovery for Home Assistant and a dynamic entity tile grid, leveraging external services and the Paho MQTT Client.
- Hardware/Driver Interaction: The project depends on the “rpi-rgb-led-matrix” library (contained in lib/rpi-rgb-led-matrix) which directly interacts with the LED matrix hardware.
- Docker and Deployment: There are multiple Docker-related files (Dockerfile, docker-compose YAMLs, .env files), indicating containerized deployment and hardware access via privileged mode.

- Hardware Drivers (via rpi-rgb-led-matrix library)
- Graphical Rendering (using PyGame CE)
- External Messaging via MQTT (input from Home Assistant and remote control)
- Configuration Management (with Dynaconf reading from settings files and environment variables)
- Commands and control messages flow from external MQTT sources (and Home Assistant) into the core systems.
- Commands from the WideBoy application to the LED matrix driver to update the display output.
- Data flows between the “systems” (e.g., scene management, entity grid updates) and the sprite rendering modules.

##### Architectural Patterns and Design Principles
- Modular Structure: Emphasize the separation of concerns. Different modules (systems, sprites, configuration) encapsulate their own functionality.
- Plugin/Extensible Sprite System: The variety of sprites (animation, image, text, tile grid) suggests an extensible design where new display components can be added.
- Integration Patterns: Outline the use of MQTT for publish/subscribe messaging, especially for decoupled communication with Home Assistant.
- Use of External Submodules: The dependency on an external LED matrix library integrated as a submodule should be noted.
- Docker-based Deployment: The configuration and use of multiple docker-compose files indicate different deployment environments (development, production, and common settings).

##### Relevant Technologies and Frameworks
- Programming Language: Python 3.10+ with type-checking (mypy), linting (flake8, black) and modern dependency management (poetry).
- Graphics Engine: PyGame CE for rendering.
- Messaging: Paho MQTT Client manages MQTT communication.
- Hardware-Specific Library: rpi-rgb-led-matrix for interfacing with HUB75 LED panels.
- Configuration: Dynaconf for flexible configuration management.
- Deployment: Docker and Docker Compose for containerized operation on Raspberry Pi.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interaction Layer
    subgraph "External Interaction Layer"
        extMQTT["MQTT Broker"]:::external
        extHA["Home Assistant"]:::external
    end

    %% Application Layer
    subgraph "Application Layer"
        subgraph "WideBoy Application"
            AA["Main Entry"]:::app
            AB["Components Module"]:::app
            AC["Configuration Management"]:::app
            AD["Core Systems & Engine"]:::app
            AE["Sprites Engine"]:::app
            AF["Scene Management"]:::app
            AG["MQTT & Home Assistant Integration"]:::app
        end
    end

    %% Driver Layer
    subgraph "Driver Layer"
        DA["rpi-rgb-led-matrix Driver"]:::driver
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        HA["Raspberry Pi Hardware"]:::hardware
        HB["LED Matrix Display"]:::hardware
    end

    %% Deployment
    subgraph "Deployment"
        D1["Docker & Deployment Files"]:::deploy
    end

    %% Connections between layers
    extMQTT -->|"publishes"| AG
    extHA   -->|"commands"| AG

    AG      -->|"updates"| AD
    AC      -->|"configures"| AD
    AA      -->|"starts"| AD
    AB      -->|"orchestrates"| AD
    AD      -->|"renders"| AE
    AD      -->|"manages"| AF
    AD      -->|"sendsCommand"| DA
    DA      -->|"updatesDisplay"| HB
    HA      -->|"hosts"| DA

    D1      -->|"deploys"| AA

    %% Click Events
    click AA "https://github.com/jinglemansweep/wideboy/blob/main/wideboy/__main__.py"
    click AB "https://github.com/jinglemansweep/wideboy/blob/main/wideboy/components.py"
    click AC "https://github.com/jinglemansweep/wideboy/blob/main/wideboy/config.py"
    click AD "https://github.com/jinglemansweep/wideboy/tree/main/wideboy/systems/"
    click AE "https://github.com/jinglemansweep/wideboy/tree/main/wideboy/sprites/"
    click AF "https://github.com/jinglemansweep/wideboy/tree/main/scenes/"
    click AG "https://github.com/jinglemansweep/wideboy/blob/main/wideboy/systems/mqtt.py"
    click DA "https://github.com/jinglemansweep/wideboy/tree/main/lib/rpi-rgb-led-matrix"
    click D1 "https://github.com/jinglemansweep/wideboy/tree/main/Dockerfile"

    %% Styles
    classDef external fill:#f9c,stroke:#333,stroke-width:2px;
    classDef app fill:#bbf,stroke:#333,stroke-width:2px;
    classDef driver fill:#bfb,stroke:#333,stroke-width:2px;
    classDef hardware fill:#fbb,stroke:#333,stroke-width:2px;
    classDef deploy fill:#ff9,stroke:#333,stroke-width:2px;
```
