# andreicatanoiu/homeguardesp architecture

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

- Interactive diagram: https://gitdiagram.com/andreicatanoiu/homeguardesp
- Repository: https://github.com/andreicatanoiu/homeguardesp

## Overview

##### Project type and purpose
- HomeGuardESP is an embedded IoT security‐monitoring firmware targeting the ESP8266/ESP32 platform.
- It integrates multiple sensors (PIR motion, MQ2 gas, potentially magnetic/contact or smoke sensors), processes their signals, and reports events in real time over Wi-Fi/MQTT to a remote application.
- It also supports over-the-air (OTA) firmware updates and a small DNS server for captive-portal style configuration.

##### File structure
- Top level: CMakeLists.txt, platformio.ini, sdkconfig.esp32dev → build and board configuration
- certs/ → TLS certificates for secure MQTT or captive portal
- / and lib/ → shared headers and libraries, documented by separate READMEs
- src/ → core firmware modules, each split into .c/.h pairs:
- main.c → application entry point and initialization
- decoder → sensor data decoding
- sensor_selector → multiplexing between different hardware inputs
- mq2_module, pir_module → driver wrappers for each sensor
- mqtt_comm → publishes and subscribes via MQTT
- dns_server → handles captive-portal DNS for initial Wi-Fi config
- wifi → Wi-Fi connection management
- ota_updates → remote firmware fetching and flashing
- system_time → real-time clock or timestamping
- settings → persistent configuration (thresholds, broker URL, Wi-Fi credentials)
- test/ → unit or integration tests

##### Extract additional insights from the README
- Emphasis on real-time alerts, MQTT integration, remote configuration via mobile app
- Future extension point: mobile app UI consumes MQTT topics and displays sensor states
- Ease of installation via PlatformIO/Arduino IDE.

1. Hardware layer
- Sensors: PIR module, MQ2 gas module, (optionally smoke/contact sensors)
- ESP32/ESP8266 MCU
- Sensor Drivers (pir_module, mq2_module)
- Sensor Selector & Decoder
- Settings & System Time
- Connectivity
- Wi-Fi Manager
- DNS Server (captive portal)
- MQTT Communication
- OTA Update Engine
3. External services
- MQTT Broker (cloud or local)
- Mobile Application / Dashboard
- Certificate Authority (for TLS certs in certs/)
b. Relationships and interactions
- Sensors → Sensor Drivers → Sensor Selector → Decoder → Settings & System Time
- Decoded data → MQTT Communication → MQTT Broker → Mobile App
- Mobile App → (optional) → Settings → firmware Settings module (via special MQTT topics)
- Firmware requests OTA updates from a remote HTTP(S) server → OTA engine → flash new firmware
- On first-boot or reconfiguration: DNS Server responds to all DNS queries to serve a captive-portal page (not shown in code, but implied)
- Wi-Fi Manager orchestrates network connectivity before MQTT or DNS modules run
c. Architectural patterns
- Modular, single-responsibility C modules (each module .c/.h handles one concern)
- Pub/Sub pattern via MQTT for decoupled event distribution
- Factory/Selector pattern in sensor_selector for dynamic sensor activation
- Over-the-air update pipeline decoupled from main monitoring loop
d. Key technologies & frameworks
- ESP-IDF or PlatformIO (CMake, platformio.ini)
- POSIX-style C modules, header files under include/
- mbedTLS (or similar) for TLS (certs/fullchain.pem)
- lwIP TCP/IP stack for Wi-Fi and DNS server
- Paho or built-in MQTT client library for ESP

##### Be comprehensive—but don’t overcomplicate
- Every src/ module as at least a labeled sub‐component
- Inter‐module dependencies (e.g., settings is used by decoder, mqtt_comm, ota_updates)
- Runtime view: how data and control signals move, how the system boots and recovers

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        PIR["PIR Motion Sensor"]:::hardware
        MQ2["MQ2 Gas Sensor"]:::hardware
        Contact["Contact/Smoke Sensor (Optional)"]:::optional
        MCU["ESP8266/ESP32 MCU"]:::hardware
    end

    %% Firmware on MCU
    subgraph "Firmware on MCU"
        direction TB

        subgraph "Sensor Drivers"
            pir_module["pir_module.c/h: Motion Sensor Driver"]:::firmware
            mq2_module["mq2_module.c/h: Gas Sensor Driver"]:::firmware
        end

        sensor_selector["sensor_selector.c/h: Sensor Selector"]:::firmware
        decoder["decoder.c/h: Sensor Data Decoder"]:::firmware

        subgraph "Settings & System Time"
            settings["settings.c/h: Persistent Settings"]:::firmware
            system_time["system_time.c/h: System Time"]:::firmware
        end

        subgraph "Connectivity"
            wifi["wifi.c/h: Wi-Fi Manager"]:::firmware
            dns_server["dns_server.c/h: Captive-Portal DNS Server"]:::firmware
            mqtt_comm["mqtt_comm.c/h: MQTT Communication"]:::firmware
        end

        ota_updates["ota_updates.c/h: OTA Update Engine"]:::firmware
        main["main.c: Application Entry Point"]:::firmware
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MQTTBroker["MQTT Broker"]:::external
        CertAuth["Certificate Authority"]:::external
        MobileApp["Mobile Application / Dashboard"]:::optional
        Tests["test/: Unit/Integration Tests"]:::external
    end

    %% Data Flows & Dependencies
    PIR --> pir_module
    MQ2 --> mq2_module
    Contact -.-> pir_module
    Contact -.-> mq2_module

    pir_module --> sensor_selector
    mq2_module --> sensor_selector
    sensor_selector --> decoder
    decoder --> settings
    decoder --> system_time

    decoder --> mqtt_comm
    mqtt_comm --> MQTTBroker
    MQTTBroker --> MobileApp
    MobileApp --> MQTTBroker
    MQTTBroker --> mqtt_comm
    mqtt_comm --> settings

    main --> wifi
    wifi --> dns_server
    wifi --> mqtt_comm
    main --> ota_updates
    ota_updates --> CertAuth

    %% Click Events
    click pir_module "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/pir_module.c"
    click pir_module "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/pir_module.h"
    click mq2_module "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/mq2_module.c"
    click mq2_module "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/mq2_module.h"
    click sensor_selector "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/sensor_selector.c"
    click sensor_selector "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/sensor_selector.h"
    click decoder "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/decoder.c"
    click decoder "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/decoder.h"
    click settings "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/settings.c"
    click settings "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/settings.h"
    click system_time "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/system_time.c"
    click system_time "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/system_time.h"
    click wifi "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/wifi.c"
    click wifi "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/wifi.h"
    click dns_server "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/dns_server.c"
    click dns_server "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/dns_server.h"
    click mqtt_comm "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/mqtt_comm.c"
    click mqtt_comm "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/mqtt_comm.h"
    click ota_updates "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/ota_updates.c"
    click ota_updates "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/ota_updates.h"
    click main "https://github.com/andreicatanoiu/homeguardesp/blob/master/src/main.c"
    click CertAuth "https://github.com/andreicatanoiu/homeguardesp/blob/master/certs/fullchain.pem"
    click Tests "https://github.com/andreicatanoiu/homeguardesp/tree/master/test/"

    %% Styles
    classDef hardware fill:#b7e4c7,stroke:#2d6a4f,color:#2d6a4f;
    classDef firmware fill:#caf0f8,stroke:#023e8a,color:#023e8a;
    classDef external fill:#ffd6a5,stroke:#e85d04,color:#e85d04;
    classDef optional stroke-dasharray: 5 5,fill:#ffffff,color:#6c757d;
```
