# kolpa/ulanzi-election architecture

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

- Interactive diagram: https://gitdiagram.com/kolpa/ulanzi-election
- Repository: https://github.com/kolpa/ulanzi-election

## Overview

##### Project Type and Purpose
- This project is a small-scale, single-script Python application designed to display live election data on a Ulanzi TC001 Smart Pixel Clock, which runs the awtrix3 firmware.
- It functions by fetching election data from the DPA electionsdata API and then publishing that data via an MQTT broker to the clock device.

##### File Structure
- The project consists of one main Python file, “ulanzi_election_display.py”, which is the central piece of logic.
- Supporting files include:
- .gitignore, .python-version, and .vscode – these are for project configuration and editor settings.
- README.md – provides usage, installation instructions, and an overview.
- env.example – the template for setting up required environment variables.
- pyproject.toml – likely used for project dependency management and build configurations.
- uv.lock – indicates use of a tool called “uv” to run the Python script.
- The simple structure suggests the architectural components are well-integrated into this single file, while external configuration and deployment details are maintained in environment and configuration files.

##### Key Components of the System
- Election Data Fetcher: A module (contained within the main script) that makes HTTP requests to the DPA electionsdata API. This component is responsible for retrieving up-to-date election information.
- MQTT Publisher: This part of the script takes fetched data and publishes it to an MQTT broker using parameters defined in the environment variables.
- Environment Configuration: A configuration module that reads from the .env file (copied from env.example). It pulls in essential variables such as API_URL, ELECTION_ID, MQTT_BROKER, and others.
- Ulanzi TC001 Smart Pixel Clock: Although not direct code, it’s the endpoint receiving data from the MQTT topic, acting as the display for the election data.

##### Relationships and Data Flow
- The Environment Configuration module reads from the .env file and supplies necessary parameters.
- The Election Data Fetcher uses these parameters (e.g., API_URL, ELECTION_ID, and ELECTION_STAGE) to pull data from the external DPA electionsdata API.
- The fetched data is then passed to the MQTT Publisher component.
- The MQTT Publisher uses the configuration (MQTT_BROKER, MQTT_PORT, MQTT_TOPIC) to send this data to the MQTT broker.
- Finally, the Ulanzi TC001 Smart Pixel Clock subscribes to the relevant MQTT topic and displays the election results.

##### Architectural Patterns and Design Principles
- Although this is a simple script-based project, it follows basic separation of concerns by isolating configuration, data fetching, and message publishing.
- The loosely coupled design allows for future modularization or integration with additional components or services.

##### Final Remarks
- This level of detail will aid in understanding, troubleshooting, and possibly extending the system in the future.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% Global Components
    ENV["Environment Config (.env)"]:::config
    RUNTIME["Runtime Environment (uv)"]:::runtime
    API["DPA Electionsdata API"]:::external
    BROKER["MQTT Broker"]:::external
    CLOCK["Ulanzi TC001 Smart Pixel Clock (awtrix3)"]:::external

    %% Application Subgraph
    subgraph "Ulanzi Election Display App"
        EDFC["Election Data Fetcher (API Client)"]:::internal
        MQTT["MQTT Publisher"]:::internal
    end

    %% Connections
    ENV -->|"supplies"| EDFC
    RUNTIME -->|"runs"| EDFC
    EDFC -->|"fetches"| API
    EDFC -->|"passes_data"| MQTT
    MQTT -->|"publishes_to"| BROKER
    BROKER -->|"distributes"| CLOCK

    %% Click Events
    click EDFC "https://github.com/kolpa/ulanzi-election/blob/main/ulanzi_election_display.py"
    click MQTT "https://github.com/kolpa/ulanzi-election/blob/main/ulanzi_election_display.py"
    click ENV "https://github.com/kolpa/ulanzi-election/blob/main/env.example"
    click RUNTIME "https://github.com/kolpa/ulanzi-election/blob/main/uv.lock"

    %% Styles
    classDef internal fill:#ffefdb,stroke:#d18b47,stroke-width:2px;
    classDef external fill:#e0f7fa,stroke:#00796b,stroke-width:2px;
    classDef config fill:#e8f5e9,stroke:#388e3c,stroke-width:2px;
    classDef runtime fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px;
```
