# mario26rgl/homecloud-iot architecture

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

- Interactive diagram: https://gitdiagram.com/mario26rgl/homecloud-iot
- Repository: https://github.com/mario26rgl/homecloud-iot

## Overview

##### Project type and purpose
- This is a Raspberry Pi–based client-side IoT application (“HomeCloud”) that reads environmental data from an Arduino sensor module and publishes it via MQTT. It also collects its own logs and metrics locally (via Filebeat) and pushes them into an Elasticsearch engine (spin-up via Docker Compose).

##### File structure
- Top level:
- application/ – Python client code
- arduino/ – sensor firmware
- extra/ – deployment/config (docker-compose.yml, Elastic repo & Filebeat config)
- startup.sh – Pi startup script
- application/ contains:
- main.py – orchestrator (initializes login, collects or subscribes to data, kicks off emits)
- login.py – handles user credentials and authentication
- emit.py – wraps MQTT publish logic
- scripts/init.sh – environment setup (e.g., install prerequisites)
- test.py – local test harness
- extra/docker-compose.yml brings up Elasticsearch (and possibly Kibana), extra/filebeat.yml pushes application logs into Elasticsearch.

##### Extract insights from README
- Confirms: “RaspberryPi client-side MQTT application.”
- No server code here — this repo focuses on the Pi-side data producer and log shipper.

##### Main components and their relationships
a. Hardware & Firmware
- Arduino Sensor Node (sensor.ino)
→ Reads temperature/humidity/other metrics
→ Publishes raw sensor readings (serial or direct MQTT)
b. Client Application (Raspberry Pi)
- main.py
‑ loads config & credentials via login.py
‑ spawns emit.py to publish data
‑ writes structured logs to disk
- emit.py
‑ connects to MQTT broker
‑ publishes sensor payloads
- test.py & scripts/init.sh
‑ local test flows & environment bootstrap
c. External Services
- MQTT Broker (could be local Mosquitto or cloud-hosted)
- Elasticsearch (spun up via Docker Compose)
- Filebeat
‑ tails the Python app’s log files
‑ forwards to Elasticsearch for indexing

##### Architectural patterns and design principles
- Publisher / Subscriber (MQTT) for decoupled sensor-to-application communication
- Modular separation of concerns:
‑ login/authentication
‑ message emission
‑ orchestration (main)
- Side-car log shipping pattern:
‑ app writes logs → Filebeat side-car reads and ships → Elasticsearch stores
- Infrastructure as code: Docker Compose defines observable services

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware Layer"
        Arduino["Sensor Node (Arduino)"]:::hardware
    end

    subgraph "Edge Application (Raspberry Pi)"
        direction TB
        Orchestrator["Orchestrator\n(main.py)"]:::app
        Login["Login Module\n(login.py)"]:::app
        Emit["Emit Module\n(emit.py)"]:::app
        Test["Test Harness\n(test.py)"]:::app
        InitScript["Env Bootstrap\n(init.sh)"]:::script
        Startup["Pi Startup\n(startup.sh)"]:::script
        Orchestrator --> Login
        Orchestrator --> Emit
        Orchestrator --> Test
        InitScript -.-> Orchestrator
        Startup -.-> Orchestrator
    end

    subgraph "Messaging Layer"
        MQTT["MQTT Broker"]:::msg
    end

    subgraph "Logging & Analytics"
        direction TB
        DockerCompose["Docker Compose\n(docker-compose.yml)"]:::config
        ConfigRepo["Elastic Repo\n(elastic.repo)"]:::config
        Filebeat["Filebeat\n(filebeat.yml)"]:::log
        ES["Elasticsearch + Kibana"]:::store
        ConfigRepo --> DockerCompose
        DockerCompose --> ES
        Filebeat --> ES
    end

    LocalFS["Local File System"]:::storage

    Arduino -->|"sensor data"| Orchestrator
    Emit -->|"publish via MQTT"| MQTT
    Orchestrator -->|"writes logs"| LocalFS
    LocalFS -->|"tails logs"| Filebeat

    click Arduino "https://github.com/mario26rgl/homecloud-iot/blob/main/arduino/sensor/sensor.ino"
    click Orchestrator "https://github.com/mario26rgl/homecloud-iot/blob/main/application/main.py"
    click Login "https://github.com/mario26rgl/homecloud-iot/blob/main/application/login.py"
    click Emit "https://github.com/mario26rgl/homecloud-iot/blob/main/application/emit.py"
    click Test "https://github.com/mario26rgl/homecloud-iot/blob/main/application/test.py"
    click InitScript "https://github.com/mario26rgl/homecloud-iot/blob/main/application/scripts/init.sh"
    click Startup "https://github.com/mario26rgl/homecloud-iot/blob/main/startup.sh"
    click DockerCompose "https://github.com/mario26rgl/homecloud-iot/blob/main/extra/docker-compose.yml"
    click ConfigRepo "https://github.com/mario26rgl/homecloud-iot/blob/main/extra/elastic.repo"
    click Filebeat "https://github.com/mario26rgl/homecloud-iot/blob/main/extra/filebeat.yml"

    classDef hardware fill:#87CEEB,stroke:#000,stroke-width:1px
    classDef app fill:#98FB98,stroke:#000,stroke-width:1px
    classDef script fill:#7FFFD4,stroke:#000,stroke-width:1px
    classDef msg fill:#FFA500,stroke:#000,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef log fill:#FFFF66,stroke:#000,stroke-width:1px
    classDef store fill:#FFEC8B,stroke:#000,stroke-width:1px
    classDef config fill:#F5DEB3,stroke:#000,stroke-width:1px
```
