# miladhalabi/led-matrix-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/miladhalabi/led-matrix-dashboard
- Repository: https://github.com/miladhalabi/led-matrix-dashboard

## Overview

1. **Project type and runtime**
   - This is an **ESP32 firmware** project, built with **PlatformIO** for an Arduino-style runtime.
   - The code is organized as a set of hardware- and feature-focused modules under `src/`, with `main.cpp` acting as the central orchestrator.

2. **System-level role of `main.cpp`**
   - `src/main.cpp` is the integration point that ties together startup, periodic updates, input handling, display rotation, network services, and scheduled actions.
   - It likely coordinates the “always-on” control loop typical of embedded dashboards: read inputs, refresh data, update the matrix, and service network/telemetry features.

3. **Display subsystem**
   - `src/display/` contains the LED matrix rendering layer for the **MAX7219 8x32 display**.
   - Based on the README and PlatformIO dependencies, this layer likely uses **MD_Parola / MD_MAX72XX** for text animation, scrolling messages, icons/glyphs, and the dashboard’s rotating views.
   - This is the user-facing output boundary for time, weather, prayer status, Telegram messages, and system notifications like OTA updates.

4. **Time, RTC, and alarm subsystem**
   - `src/time/` manages the **DS3231 RTC** and the current time source used by the dashboard.
   - This module is the core authority for clock display, alarm triggering, and keeping time stable when network access is unavailable.
   - The alarm behavior is probably coupled to audio playback through the DFPlayer and to display notifications.

5. **Prayer-time subsystem**
   - `src/prayerTime/` handles fetching and scheduling daily prayer times, using the **Aladhan API** as described in the README.
   - This subsystem likely computes or stores the day’s prayer schedule and determines when to trigger the Azan/alarm behavior.
   - It is a separate scheduling concern from the general clock/alarm logic, but both feed the same UI and audio outputs.

6. **Weather subsystem**
   - `src/weather/` integrates with the **Open-Meteo API** for current weather and temperature.
   - Weather data is an external input that feeds the display rotation, especially the date/weather screen mentioned in the README.
   - The architecture likely treats weather as periodically refreshed network data with local caching/fallback behavior when offline.

7. **Telegram control plane**
   - `src/telegram/` is the remote management surface, built on **AsyncTelegram2**.
   - It supports interactive control via inline keyboards, message handling, and OTA update acceptance from a `.bin` file sent to the bot.
   - This is the main remote “control plane” for changing settings, pushing messages to the matrix, toggling alarm/prayer features, and triggering firmware updates.

8. **Local input and offline control**
   - `src/encoder/` implements the **rotary encoder** and button-driven local menu.
   - This is the offline fallback/control path when the device is not using Telegram, and it exposes key configuration functions such as time, alarm, brightness, volume, and prayer toggles.
   - The encoder subsystem is important because it provides a fully local management boundary independent of the network stack.

9. **Connectivity and provisioning**
   - `src/wifi/` handles WiFi connection management and the initial **captive portal** configuration flow via **IotWebConf**.
   - The README describes a provisioning hotspot and recovery behavior, so this module likely manages first boot setup, reconnection, and internet availability checks.
   - This subsystem is the bridge between the device and all remote dependencies: Telegram, weather, prayer-time APIs, and OTA.

10. **Persistence, settings, and flash handling**
   - `src/flashUtils/`, `src/setters/`, `src/usersManagement/`, and `src/utils/` form the non-volatile configuration and support layer.
   - These modules likely store and update device preferences such as WiFi credentials, alarm state, brightness, volume, selected music, Telegram identity, and other user settings.
   - `usersManagement` is probably the authorization boundary for Telegram chat access, while `setters` encapsulates state changes driven by either Telegram or the encoder menu.

11. **Parsing, formatting, and conversion helpers**
   - `src/parsers/`, `src/formaters/`, and `src/converters/` are shared utility layers used to move data between external formats and display-ready/internal representations.
   - Typical responsibilities here would include JSON parsing, string shaping for the matrix display, time/date formatting, and unit/value conversion for weather or clock fields.
   - These modules reduce coupling between network data sources and presentation logic.

12. **Audio and media control**
   - While there is no dedicated top-level audio folder, the README shows the device uses a **DFPlayer Mini** and SD card for Azan/alarm playback.
   - Audio control is likely coordinated across the alarm/prayer-time logic and whichever module handles sound selection and volume settings.
   - The `src/backups/` directory suggests prior iterations or experimental state for some of this behavior, but the active architecture is centered on the current modules above.

13. **Testing and build artifacts**
   - `test/prayTimeTest.cpp` indicates at least one focused test target around prayer-time behavior.
   - `firmware/firmware.bin` is the build artifact used for deployment and also the OTA payload accepted over Telegram.
   - The `platformio.ini` file is the build/dependency boundary that defines the embedded toolchain and third-party libraries.

14. **End-to-end data flow**
   - Inputs enter the system from four places: **RTC/local encoder**, **WiFi + APIs**, **Telegram**, and **SD/audio media**.
   - Those inputs are normalized by parsers/setters/converters, persisted through flash utilities where needed, and then consumed by the display, alarm, and audio subsystems.
   - The main architectural pattern is an **event-driven embedded controller** with two interaction surfaces: a local physical UI and a remote Telegram UI, both feeding the same device state.

Main entry points: [`src/main.cpp`](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/main.cpp) (Main loop), [`src/setters/setters.h`](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/setters/setters.h) (Setters), [`src/telegram/telegram.h`](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/telegram/telegram.h) (Telegram), [`src/prayerTime/prayerTime.h`](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/prayerTime/prayerTime.h) (Prayer time)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_main["Main loop<br/>orchestrator<br/>[main.cpp]"]
  node_time["RTC time<br/>clock<br/>[time.h]"]
end

subgraph group_ui["User interfaces"]
  node_display["Display<br/>matrix UI<br/>[display.h]"]
  node_encoder["Encoder<br/>local input<br/>[encoder.h]"]
  node_telegram["Telegram<br/>remote control<br/>[telegram.h]"]
end

subgraph group_services["External services"]
  node_wifi["WiFi<br/>connectivity<br/>[wifi.h]"]
  node_weather["Weather<br/>api client<br/>[weather.h]"]
  node_prayer["Prayer time<br/>scheduler<br/>[prayerTime.h]"]
end

subgraph group_support["Support layers"]
  node_flash["Flash utils<br/>persistence<br/>[flashUtils.h]"]
  node_setters["Setters<br/>state update<br/>[setters.h]"]
  node_users["Users<br/>auth<br/>[usersManagement.h]"]
  node_parsers["Parsers<br/>data parsing<br/>[parsers.h]"]
  node_formaters["Formaters<br/>presentation<br/>[formaters.h]"]
  node_converters["Converters<br/>transforms<br/>[converters.h]"]
  node_utils["Utils<br/>shared helpers<br/>[utils.h]"]
  node_firmware["Firmware bin<br/>artifact<br/>[firmware.bin]"]
  node_test_prayer["Prayer test<br/>[prayTimeTest.cpp]"]
end

node_main -->|"reads clock"| node_time
node_main -->|"drives UI"| node_display
node_main -->|"reads input"| node_encoder
node_main -->|"handles remote"| node_telegram
node_main -->|"connects"| node_wifi
node_main -->|"refreshes data"| node_weather
node_main -->|"schedules"| node_prayer
node_main -->|"applies changes"| node_setters
node_main -->|"persists"| node_flash
node_telegram -->|"authenticates"| node_users
node_telegram -.->|"ota payload"| node_firmware
node_telegram -->|"remote config"| node_setters
node_encoder -->|"local config"| node_setters
node_wifi -->|"fetches"| node_weather
node_wifi -->|"fetches"| node_prayer
node_weather -->|"parses response"| node_parsers
node_prayer -->|"parses response"| node_parsers
node_display -->|"formats text"| node_formaters
node_display -->|"converts values"| node_converters
node_setters -->|"stores state"| node_flash
node_setters -->|"uses helpers"| node_utils
node_formaters -->|"uses helpers"| node_utils
node_parsers -->|"uses helpers"| node_utils
node_converters -->|"uses helpers"| node_utils
node_test_prayer -->|"verifies"| node_prayer

click node_main "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/main.cpp"
click node_display "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/display/display.h"
click node_encoder "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/encoder/encoder.h"
click node_telegram "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/telegram/telegram.h"
click node_wifi "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/wifi/wifi.h"
click node_weather "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/weather/weather.h"
click node_prayer "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/prayerTime/prayerTime.h"
click node_time "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/time/time.h"
click node_flash "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/flashUtils/flashUtils.h"
click node_setters "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/setters/setters.h"
click node_users "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/usersManagement/usersManagement.h"
click node_parsers "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/parsers/parsers.h"
click node_formaters "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/formaters/formaters.h"
click node_converters "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/converters/converters.h"
click node_utils "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/utils/utils.h"
click node_firmware "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/firmware/firmware.bin"
click node_test_prayer "https://github.com/miladhalabi/led-matrix-dashboard/blob/main/test/prayTimeTest.cpp"

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_time toneBlue
class node_display,node_encoder,node_telegram toneAmber
class node_wifi,node_weather,node_prayer toneMint
class node_flash,node_setters,node_users,node_parsers,node_formaters,node_converters,node_utils,node_firmware,node_test_prayer toneRose
```

## Components

### Core runtime

Embedded control loop and shared device state

- [Main loop](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/main.cpp): orchestrator · Startup and periodic coordination for the firmware · `src/main.cpp`
- [RTC time](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/time/time.h): clock · DS3231 timekeeping and alarm timing source · `src/time/time.h`

### User interfaces

Local and remote control surfaces

- [Display](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/display/display.h): matrix UI · MAX7219 dashboard rendering and screen rotation · `src/display/display.h`
- [Encoder](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/encoder/encoder.h): local input · Rotary encoder and button-driven local menu · `src/encoder/encoder.h`
- [Telegram](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/telegram/telegram.h): remote control · AsyncTelegram2 command and OTA control plane · `src/telegram/telegram.h`

### External services

Networked data sources and provisioning

- [WiFi](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/wifi/wifi.h): connectivity · Connection management and captive portal provisioning · `src/wifi/wifi.h`
- [Weather](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/weather/weather.h): api client · Open-Meteo weather retrieval and refresh logic · `src/weather/weather.h`
- [Prayer time](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/prayerTime/prayerTime.h): scheduler · Daily prayer schedule and Azan timing · `src/prayerTime/prayerTime.h`

### Support layers

Persistence, parsing, and formatting helpers

- [Flash utils](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/flashUtils/flashUtils.h): persistence · Non-volatile storage helpers for device settings · `src/flashUtils/flashUtils.h`
- [Setters](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/setters/setters.h): state update · Centralized device state mutations from UI and services · `src/setters/setters.h`
- [Users](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/usersManagement/usersManagement.h): auth · Telegram chat authorization and user management · `src/usersManagement/usersManagement.h`
- [Parsers](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/parsers/parsers.h): data parsing · Input parsing for API and message payloads · `src/parsers/parsers.h`
- [Formaters](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/formaters/formaters.h): presentation · String and payload formatting for display and messages · `src/formaters/formaters.h`
- [Converters](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/converters/converters.h): transforms · Value and unit conversion helpers · `src/converters/converters.h`
- [Utils](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/src/utils/utils.h): shared helpers · Common utility functions used across modules · `src/utils/utils.h`
- [Firmware bin](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/firmware/firmware.bin): artifact · Built binary used for deployment and Telegram OTA · `firmware/firmware.bin`
- [Prayer test](https://github.com/miladhalabi/led-matrix-dashboard/blob/main/test/prayTimeTest.cpp): test · Focused test target for prayer-time behavior · `test/prayTimeTest.cpp`

## Connections

- Main loop → RTC time: reads clock · Uses RTC time for display, alarms, and scheduling
- Main loop → Display: drives UI · Refreshes dashboard screens and notifications
- Main loop → Encoder: reads input · Polls local controls and menu actions
- Main loop → Telegram: handles remote · Services bot commands and interactive control
- Main loop → WiFi: connects · Depends on network availability for remote services
- Main loop → Weather: refreshes data · Pulls weather updates into the dashboard
- Main loop → Prayer time: schedules · Evaluates prayer times and Azan triggers
- Main loop → Setters: applies changes · Routes configuration changes into shared device state
- Main loop → Flash utils: persists · Stores and restores settings across reboots
- Telegram → Users: authenticates · Restricts control to allowed chats/users
- Telegram → Firmware bin: ota payload · Accepts firmware updates as uploaded binary
- Telegram → Setters: remote config · Updates brightness, volume, alarm, and feature toggles
- Encoder → Setters: local config · Changes settings through physical controls
- WiFi → Weather: fetches · Provides connectivity for weather API access
- WiFi → Prayer time: fetches · Provides connectivity for prayer-time API access
- Weather → Parsers: parses response · Converts API payloads into internal data
- Prayer time → Parsers: parses response · Processes prayer schedule payloads
- Display → Formaters: formats text · Turns data into matrix-friendly strings
- Display → Converters: converts values · Adapts units and time fields for presentation
- Setters → Flash utils: stores state · Writes persistent preferences and identity data
- Setters → Utils: uses helpers · Shares common logic for state handling
- Formaters → Utils: uses helpers · Relies on shared formatting utilities
- Parsers → Utils: uses helpers · Shares common parsing helpers
- Converters → Utils: uses helpers · Shares common conversion helpers
- Prayer test → Prayer time: verifies · Exercises prayer-time calculations and scheduling
