# frankevin25/ecowatt-2026 architecture

> Architecture diagram of the GitHub repository frankevin25/ecowatt-2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frankevin25/ecowatt-2026
- Repository: https://github.com/frankevin25/ecowatt-2026

## Overview

EcoWatt is a residential electricity-monitoring system: firmware measures electrical signals, sends telemetry over MQTT, and a documented backend stores and analyzes it for dashboards and user-facing insights. The repository contains hardware firmware and simulation assets, but the README-described backend, ML pipeline, conversational AI, and dashboard are absent from the tree; those components are shown with null paths and documented relationships only. Firmware excerpts show measurement calls and MQTT publishing; the Arduino-to-ESP32 handoff and downstream product capabilities are documented in the README.

Main entry points: [`hardware/firmware/arduino/src/main.cpp`](https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/arduino/src/main.cpp) (Arduino sampler), [`hardware/firmware/esp32/src/main.cpp`](https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/esp32/src/main.cpp) (ESP32 telemetry), [`hardware/firmware/esp32/src/MqttService.cpp`](https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/esp32/src/MqttService.cpp) (MQTT service), [`hardware/firmware/arduino/src/electricMeasurement.cpp`](https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/arduino/src/electricMeasurement.cpp) (Signal measurement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Device firmware"]
  node_arduino["Arduino sampler<br/>[main.cpp]"]
  node_measurement["Signal measurement"]
  node_esp32["ESP32 telemetry<br/>[main.cpp]"]
  node_mqtt_service["MQTT service<br/>[MqttService.cpp]"]
end

subgraph group_ingest["Telemetry platform"]
  node_backend["Django backend"]
  node_timeseries[("Time-series store")]
end

subgraph group_analytics["Energy analytics"]
  node_preprocess["Window preprocessing"]
  node_sgn["SGN NILM"]
  node_seq2point["Seq2Point backup"]
  node_forecast["Cost forecast"]
end

subgraph group_experience["User experience"]
  node_assistant["Conversational AI"]
  node_dashboard["Energy dashboard"]
end

node_home(("Home electricity"))
node_broker["MQTT broker"]
node_gemini["Gemini API"]
node_claude["Claude API"]
node_resident(("Resident"))

node_home -->|"provides signals"| node_measurement
node_arduino -->|"runs measurement"| node_measurement
node_arduino -->|"sends TTL serial"| node_esp32
node_esp32 -->|"publishes telemetry"| node_mqtt_service
node_mqtt_service -->|"publishes MQTT"| node_broker
node_broker -->|"delivers telemetry"| node_backend
node_backend -->|"stores readings"| node_timeseries
node_backend -->|"starts pipeline"| node_preprocess
node_preprocess -->|"feeds windows"| node_sgn
node_preprocess -->|"feeds backup"| node_seq2point
node_backend -->|"runs prediction"| node_forecast
node_sgn -->|"returns appliance loads"| node_backend
node_seq2point -->|"returns appliance loads"| node_backend
node_backend -->|"provides consumption context"| node_assistant
node_assistant -->|"requests advice"| node_gemini
node_assistant -.->|"backup advice"| node_claude
node_backend -->|"serves results"| node_dashboard
node_dashboard -->|"shows insights"| node_resident
node_resident -->|"requests recommendations"| node_assistant

click node_arduino "https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/arduino/src/main.cpp"
click node_measurement "https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/arduino/src/electricMeasurement.cpp"
click node_esp32 "https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/esp32/src/main.cpp"
click node_mqtt_service "https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/esp32/src/MqttService.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_arduino,node_measurement,node_esp32,node_mqtt_service toneBlue
class node_backend,node_timeseries toneAmber
class node_preprocess,node_sgn,node_seq2point,node_forecast,node_gemini,node_claude toneMint
class node_assistant,node_dashboard toneRose
class node_home,node_broker,node_resident toneIndigo
```

## Components

### Device firmware

- [Arduino sampler](https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/arduino/src/main.cpp): `hardware/firmware/arduino/src/main.cpp`
- [Signal measurement](https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/arduino/src/electricMeasurement.cpp): `hardware/firmware/arduino/src/electricMeasurement.cpp`
- [ESP32 telemetry](https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/esp32/src/main.cpp): `hardware/firmware/esp32/src/main.cpp`
- [MQTT service](https://github.com/frankevin25/ecowatt-2026/blob/main/hardware/firmware/esp32/src/MqttService.cpp): `hardware/firmware/esp32/src/MqttService.cpp`

### Telemetry platform

- **Django backend**
- **Time-series store**

### Energy analytics

- **Window preprocessing**
- **SGN NILM**
- **Seq2Point backup**
- **Cost forecast**

### User experience

- **Conversational AI**
- **Energy dashboard**

### Other components

- **Home electricity**
- **MQTT broker**
- **Gemini API**
- **Claude API**
- **Resident**

## Connections

- Home electricity → Signal measurement: provides signals (evidence: `README.md`)
- Arduino sampler → Signal measurement: runs measurement (evidence: `hardware/firmware/arduino/src/main.cpp`)
- Arduino sampler → ESP32 telemetry: sends TTL serial (evidence: `README.md`)
- ESP32 telemetry → MQTT service: publishes telemetry (evidence: `hardware/firmware/esp32/src/main.cpp`)
- MQTT service → MQTT broker: publishes MQTT (evidence: `hardware/firmware/esp32/src/MqttService.cpp`)
- MQTT broker → Django backend: delivers telemetry (evidence: `README.md`)
- Django backend → Time-series store: stores readings (evidence: `README.md`)
- Django backend → Window preprocessing: starts pipeline (evidence: `README.md`)
- Window preprocessing → SGN NILM: feeds windows (evidence: `README.md`)
- Window preprocessing → Seq2Point backup: feeds backup (evidence: `README.md`)
- Django backend → Cost forecast: runs prediction (evidence: `README.md`)
- SGN NILM → Django backend: returns appliance loads (evidence: `README.md`)
- Seq2Point backup → Django backend: returns appliance loads (evidence: `README.md`)
- Django backend → Conversational AI: provides consumption context (evidence: `README.md`)
- Conversational AI → Gemini API: requests advice (evidence: `README.md`)
- Conversational AI → Claude API: backup advice (evidence: `README.md`)
- Django backend → Energy dashboard: serves results (evidence: `README.md`)
- Energy dashboard → Resident: shows insights (evidence: `README.md`)
- Resident → Conversational AI: requests recommendations (evidence: `README.md`)
