# emsesp/ems-esp architecture

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

- Interactive diagram: https://gitdiagram.com/emsesp/ems-esp
- Repository: https://github.com/emsesp/ems-esp

## Overview

##### Project Type and Purpose
- This is a full-stack embedded firmware project for ESP8266/ESP32 (EMS-ESP v2).
- It combines:
- A native microcontroller “backend” (C++ firmware) talking to EMS-bus equipment over UART.
- A multi-user secure web “frontend” (React/TypeScript served by ESPAsyncWebServer).
- External integrations: MQTT (for Home Assistant), Telnet/Serial console, NTP, OTA updates.

##### File-Structure Analysis
- Top-level:
- src/             ← Core firmware source (device drivers, services, web API)
- interface/       ← React web UI (REST+WebSocket client)
- lib/, lib_standalone/ ← Embedded libraries (ArduinoJson, AsyncTCP/WebServer, UUID console, etc.)
- scripts/, makefile, platformio.ini ← Build & deployment helpers (Python scripts, PlatformIO config).
- Patterns:
- “framework” services under lib/framework implement StatefulService pattern.
- REST/WebSocket controllers in src/ expose internal services.
- React “components”, “authentication”, “api”, “mqtt” folders → client-side MVC.

##### README Insights
- Emphasizes:
- Web UI for settings/status.
- MQTT Discovery for Home Assistant.
- Standalone AP or join network.
- Console via Serial/Telnet.
- Libraries: esp8266-react, AsyncMqttClient, ESPAsyncWebServer/TCP.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        Browser["Web Browser"]:::external
        MQTTBroker["MQTT Broker"]:::external
        NTPSrv["NTP Server"]:::external
        TelnetClient["Telnet/Serial Client"]:::external
        HomeAssistant["Home Assistant"]:::external
    end

    %% Frontend
    subgraph "Frontend Web UI"
        ReactApp["React App (interface)"]:::frontend
    end

    %% Firmware Web/API Layer
    subgraph "Firmware Web/API Layer"
        WebServer["ESPAsyncWebServer"]:::api
        WebAPI["WebAPIService"]:::api
        WebSettings["WebSettingsService"]:::api
        WebDevices["WebDevicesService"]:::api
        WebStatus["WebStatusService"]:::api
        WS["WebSocketTxRx"]:::api
    end

    %% Firmware Services
    subgraph "Firmware Services"
        APServ["APSettingsService"]:::service
        APStat["APStatus"]:::service
        WiFiServ["WiFiSettingsService"]:::service
        WiFiStat["WiFiStatus"]:::service
        NTPServ["NTPSettingsService"]:::service
        NTPStat["NTPStatus"]:::service
        OTAServ["OTASettingsService"]:::service
        FRServ["FactoryResetService"]:::service
        SecServ["SecuritySettingsService"]:::service
        SysStat["SystemStatus"]:::service
        MqttServ["MqttSettingsService"]:::service
        MqttStat["MqttStatus"]:::service
        MqttPubSub["MqttPubSub"]:::service
        UploadServ["UploadFirmwareService"]:::service
    end

    %% Firmware Drivers & Storage
    subgraph "Firmware Drivers & Storage"
        UARTDrv["EMS UART Driver"]:::driver
        WiFiDrv["WiFi Driver"]:::driver
        FlashFS["SPIFFS (SPI Flash)"]:::storage
        OTAUpd["OTA Updater"]:::driver
        NTPClient["NTP Client"]:::driver
    end

    %% Console Layer
    subgraph "Console Layer"
        Console["Serial/Telnet Console"]:::console
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        EMSBus["EMS-Bus Transceiver"]:::hardware
    end

    %% Build & Packaging Pipeline
    subgraph "Build & Packaging"
        BuildReact["scripts/build_interface.py"]:::build
        BuildFW["PlatformIO & scripts/firmware_upload.py"]:::build
    end

    %% Data Flows
    Browser -->|"HTTP/HTTPS"| ReactApp
    ReactApp -->|"REST/WS"| WebServer
    WebServer --> WebAPI
    WebServer --> WebSettings
    WebServer --> WebDevices
    WebServer --> WebStatus
    WebServer --> WS

    WebAPI -->|invokes| APServ
    WebSettings -->|invokes| WiFiServ
    WebStatus -->|invokes| SysStat
    WebAPI -->|invokes| NTPServ
    WebSettings -->|invokes| OTAServ
    WebAPI -->|invokes| SecServ
    WebSettings -->|invokes| FRServ
    WebAPI -->|invokes| MqttServ
    WebStatus -->|invokes| MqttStat
    WebAPI -->|invokes| UploadServ

    APServ <--> FlashFS
    WiFiServ <--> FlashFS
    NTPServ <--> FlashFS
    OTAServ <--> FlashFS
    SecServ <--> FlashFS
    FRServ <--> FlashFS
    SysStat <--> FlashFS
    MqttServ <--> FlashFS

    WiFiServ -->|controls| WiFiDrv
    NTPServ -->|sync| NTPClient
    UploadServ -->|updates via| OTAUpd
    MqttServ --> MqttPubSub
    MqttPubSub -->|publishes| MQTTBroker

    UARTDrv --> EMSBus

    TelnetClient -->|"Telnet/Serial"| Console

    %% External integrations
    NTPClient --> NTPSrv
    MQTTBroker --> HomeAssistant

    %% Build flows
    BuildReact -.->|packages UI| FlashFS
    BuildFW -.->|flashes MCU| UARTDrv

    %% Click Events
    click UARTDrv "https://github.com/emsesp/ems-esp/blob/main/src/uart/emsuart_esp8266.cpp"
    click FlashFS "https://github.com/emsesp/ems-esp/tree/main/interface/public/"
    click APServ "https://github.com/emsesp/ems-esp/blob/main/lib/framework/APSettingsService.cpp"
    click APStat "https://github.com/emsesp/ems-esp/blob/main/lib/framework/APStatus.cpp"
    click WiFiServ "https://github.com/emsesp/ems-esp/blob/main/lib/framework/WiFiSettingsService.cpp"
    click WiFiStat "https://github.com/emsesp/ems-esp/blob/main/lib/framework/WiFiStatus.cpp"
    click NTPServ "https://github.com/emsesp/ems-esp/blob/main/lib/framework/NTPSettingsService.cpp"
    click NTPStat "https://github.com/emsesp/ems-esp/blob/main/lib/framework/NTPStatus.cpp"
    click OTAServ "https://github.com/emsesp/ems-esp/blob/main/lib/framework/OTASettingsService.cpp"
    click FRServ "https://github.com/emsesp/ems-esp/blob/main/lib/framework/FactoryResetService.cpp"
    click SecServ "https://github.com/emsesp/ems-esp/blob/main/lib/framework/SecuritySettingsService.cpp"
    click SysStat "https://github.com/emsesp/ems-esp/blob/main/lib/framework/SystemStatus.cpp"
    click MqttServ "https://github.com/emsesp/ems-esp/blob/main/lib/framework/MqttSettingsService.cpp"
    click MqttStat "https://github.com/emsesp/ems-esp/blob/main/lib/framework/MqttStatus.cpp"
    click MqttPubSub "https://github.com/emsesp/ems-esp/blob/main/lib/framework/MqttPubSub.h"
    click UploadServ "https://github.com/emsesp/ems-esp/blob/main/lib/framework/UploadFirmwareService.cpp"
    click WebAPI "https://github.com/emsesp/ems-esp/blob/main/src/WebAPIService.cpp"
    click WebSettings "https://github.com/emsesp/ems-esp/blob/main/src/WebSettingsService.cpp"
    click WebDevices "https://github.com/emsesp/ems-esp/blob/main/src/WebDevicesService.cpp"
    click WebStatus "https://github.com/emsesp/ems-esp/blob/main/src/WebStatusService.cpp"
    click WS "https://github.com/emsesp/ems-esp/blob/main/lib/framework/WebSocketTxRx.h"
    click Console "https://github.com/emsesp/ems-esp/blob/main/src/console.cpp"
    click BuildReact "https://github.com/emsesp/ems-esp/blob/main/scripts/build_interface.py"
    click BuildFW "https://github.com/emsesp/ems-esp/blob/main/scripts/firmware_upload.py"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef frontend fill:#cc99ff,stroke:#663399,stroke-width:1px
    classDef api fill:#ffcc99,stroke:#ff6600,stroke-width:1px
    classDef service fill:#ccff99,stroke:#339900,stroke-width:1px
    classDef driver fill:#99ccff,stroke:#0066cc,stroke-width:1px
    classDef storage fill:#99ccff,stroke:#0066cc,stroke-width:1px,stroke-dasharray: 5 5
    classDef console fill:#eeeeee,stroke:#999999,stroke-width:1px
    classDef hardware fill:#99ccff,stroke:#003399,stroke-width:1px
    classDef build fill:#dddddd,stroke:#666666,stroke-width:1px,stroke-dasharray: 2 2
```
