# radicalsanta/greenpulse architecture

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

- Interactive diagram: https://gitdiagram.com/radicalsanta/greenpulse
- Repository: https://github.com/radicalsanta/greenpulse

## Overview

GreenPulse is an environmental monitoring and ecosystem-stress assessment system: ESP32 sensors produce scored telemetry, the backend ingests and stores it, and a dashboard endpoint combines the latest reading with weather and air-quality context to return EMS scores, alerts, and guidance. MQTT connects device publishing to backend ingestion; WebSockets broadcast new readings. The frontend is present, but its API wiring is not shown. Firmware and unsampled backend capabilities are represented only where the source index or excerpts support them.

Main entry points: [`GreenPulseBackend/app/ems/pipeline.py`](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/ems/pipeline.py) (EMS orchestration), [`GreenPulseFirmware/src/main.cpp`](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/main.cpp) (Sampling loop), [`GreenPulseBackend/app/mqtt_client.py`](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/mqtt_client.py) (MQTT subscriber), [`GreenPulseBackend/app/main.py`](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/main.py) (FastAPI routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["ESP32 Firmware"]
  node_firmware_main["Sampling loop<br/>[main.cpp]"]
  node_sensor_modules["Sensor modules<br/>[CO2Sensor.cpp]"]
  node_gps["GPS location<br/>[GPS.cpp]"]
  node_buffers["Sample buffers<br/>[CircularBuffer.cpp]"]
  node_device_scores["Sensor scoring<br/>[DataProcessor.cpp]"]
  node_telemetry["Telemetry serialization"]
  node_wifi["Wi-Fi connection<br/>[WifiManager.cpp]"]
  node_device_mqtt["MQTT publisher<br/>[MQTTClient.cpp]"]
end

subgraph group_ingest["Telemetry Backend"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_mqtt_ingest["MQTT subscriber<br/>[mqtt_client.py]"]
  node_database[("Telemetry database<br/>[database.py]")]
  node_reading_model["Reading model<br/>[model.py]"]
  node_websocket["WebSocket broadcast"]
end

subgraph group_assessment["EMS Assessment"]
  node_pipeline["EMS orchestration<br/>[pipeline.py]"]
  node_sensor_scores["Context scoring<br/>[sensor_scores.py]"]
  node_aqi["AQI calculation<br/>[aqi.py]"]
  node_dimensions["EMS dimensions<br/>[dimensions.py]"]
  node_alerts["Alert calculation<br/>[alerts.py]"]
  node_playbook["Deterministic playbook<br/>[playbook.py]"]
  node_llama["LLM advisory<br/>[llama.py]"]
end

subgraph group_context["Environmental Context"]
  node_weather["Weather retrieval<br/>[open_meteo.py]"]
  node_air_quality["Air retrieval<br/>[open_meteo_air.py]"]
end

subgraph group_presentation["Dashboard"]
  node_frontend["Dashboard frontend<br/>[app.py]"]
end

node_operator(("Dashboard user"))
node_broker["MQTT broker"]
node_weather_service(("Open-Meteo services"))

node_firmware_main -->|"reads sensors"| node_sensor_modules
node_firmware_main -->|"reads location"| node_gps
node_firmware_main -.->|"buffers samples"| node_buffers
node_firmware_main -->|"calculates scores"| node_device_scores
node_firmware_main -->|"serializes telemetry"| node_telemetry
node_firmware_main -.->|"initializes Wi-Fi"| node_wifi
node_firmware_main -->|"publishes telemetry"| node_device_mqtt
node_device_mqtt -->|"publishes MQTT"| node_broker
node_broker -->|"delivers telemetry"| node_mqtt_ingest
node_mqtt_ingest -->|"saves readings"| node_database
node_mqtt_ingest -->|"builds reading"| node_reading_model
node_mqtt_ingest -->|"broadcasts readings"| node_websocket
node_api -->|"queries readings"| node_database
node_api -->|"creates readings"| node_reading_model
node_api -->|"runs assessment"| node_pipeline
node_pipeline -->|"fetches weather"| node_weather
node_pipeline -->|"fetches air data"| node_air_quality
node_weather -.->|"requests weather"| node_weather_service
node_air_quality -->|"requests air data"| node_weather_service
node_pipeline -->|"scores context"| node_sensor_scores
node_pipeline -->|"calculates AQI"| node_aqi
node_pipeline -->|"calculates dimensions"| node_dimensions
node_pipeline -->|"calculates alert"| node_alerts
node_pipeline -->|"generates playbook"| node_playbook
node_pipeline -->|"generates advisory"| node_llama
node_operator -.->|"views dashboard"| node_frontend
node_frontend -.->|"requests dashboard"| node_api

click node_firmware_main "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/main.cpp"
click node_sensor_modules "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/CO2Sensor.cpp"
click node_gps "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/GPS.cpp"
click node_buffers "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/CircularBuffer.cpp"
click node_device_scores "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/DataProcessor.cpp"
click node_telemetry "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/TelemetrySerializer.cpp"
click node_wifi "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/WifiManager.cpp"
click node_device_mqtt "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/MQTTClient.cpp"
click node_api "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/main.py"
click node_mqtt_ingest "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/mqtt_client.py"
click node_database "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/database.py"
click node_reading_model "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/model.py"
click node_websocket "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/connection_manager.py"
click node_pipeline "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/ems/pipeline.py"
click node_sensor_scores "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/processing/sensor_scores.py"
click node_aqi "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/ems/aqi.py"
click node_dimensions "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/ems/dimensions.py"
click node_alerts "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/ems/alerts.py"
click node_playbook "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/advisory/playbook.py"
click node_llama "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/advisory/llama.py"
click node_weather "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/external/open_meteo.py"
click node_air_quality "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/external/open_meteo_air.py"
click node_frontend "https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFrontend/app.py"

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_firmware_main,node_sensor_modules,node_gps,node_buffers,node_device_scores,node_telemetry,node_wifi,node_device_mqtt,node_operator toneBlue
class node_api,node_mqtt_ingest,node_database,node_reading_model,node_websocket toneAmber
class node_pipeline,node_sensor_scores,node_aqi,node_dimensions,node_alerts,node_playbook,node_llama toneMint
class node_weather,node_air_quality toneRose
class node_frontend,node_broker,node_weather_service toneIndigo
```

## Components

### ESP32 Firmware

- [Sampling loop](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/main.cpp): `GreenPulseFirmware/src/main.cpp`
- [Sensor modules](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/CO2Sensor.cpp): `GreenPulseFirmware/src/CO2Sensor.cpp`
- [GPS location](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/GPS.cpp): `GreenPulseFirmware/src/GPS.cpp`
- [Sample buffers](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/CircularBuffer.cpp): `GreenPulseFirmware/src/CircularBuffer.cpp`
- [Sensor scoring](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/DataProcessor.cpp): `GreenPulseFirmware/src/DataProcessor.cpp`
- [Telemetry serialization](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/TelemetrySerializer.cpp): `GreenPulseFirmware/src/TelemetrySerializer.cpp`
- [Wi-Fi connection](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/WifiManager.cpp): `GreenPulseFirmware/src/WifiManager.cpp`
- [MQTT publisher](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFirmware/src/MQTTClient.cpp): `GreenPulseFirmware/src/MQTTClient.cpp`

### Telemetry Backend

- [FastAPI routes](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/main.py): `GreenPulseBackend/app/main.py`
- [MQTT subscriber](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/mqtt_client.py): `GreenPulseBackend/app/mqtt_client.py`
- [Telemetry database](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/database.py): `GreenPulseBackend/app/database.py`
- [Reading model](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/model.py): `GreenPulseBackend/app/model.py`
- [WebSocket broadcast](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/connection_manager.py): `GreenPulseBackend/app/connection_manager.py`

### EMS Assessment

- [EMS orchestration](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/ems/pipeline.py): `GreenPulseBackend/app/ems/pipeline.py`
- [Context scoring](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/processing/sensor_scores.py): `GreenPulseBackend/app/processing/sensor_scores.py`
- [AQI calculation](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/ems/aqi.py): `GreenPulseBackend/app/ems/aqi.py`
- [EMS dimensions](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/ems/dimensions.py): `GreenPulseBackend/app/ems/dimensions.py`
- [Alert calculation](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/ems/alerts.py): `GreenPulseBackend/app/ems/alerts.py`
- [Deterministic playbook](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/advisory/playbook.py): `GreenPulseBackend/app/advisory/playbook.py`
- [LLM advisory](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/advisory/llama.py): `GreenPulseBackend/app/advisory/llama.py`

### Environmental Context

- [Weather retrieval](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/external/open_meteo.py): `GreenPulseBackend/app/external/open_meteo.py`
- [Air retrieval](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseBackend/app/external/open_meteo_air.py): `GreenPulseBackend/app/external/open_meteo_air.py`

### Dashboard

- [Dashboard frontend](https://github.com/radicalsanta/greenpulse/blob/main/GreenPulseFrontend/app.py): `GreenPulseFrontend/app.py`

### Other components

- **Dashboard user**
- **MQTT broker**
- **Open-Meteo services**

## Connections

- Sampling loop → Sensor modules: reads sensors (evidence: `GreenPulseFirmware/src/main.cpp`)
- Sampling loop → GPS location: reads location (evidence: `GreenPulseFirmware/src/main.cpp`)
- Sampling loop → Sample buffers: buffers samples
- Sampling loop → Sensor scoring: calculates scores (evidence: `GreenPulseFirmware/src/main.cpp`)
- Sampling loop → Telemetry serialization: serializes telemetry (evidence: `GreenPulseFirmware/src/main.cpp`)
- Sampling loop → Wi-Fi connection: initializes Wi-Fi
- Sampling loop → MQTT publisher: publishes telemetry (evidence: `GreenPulseFirmware/src/main.cpp`)
- MQTT publisher → MQTT broker: publishes MQTT (evidence: `GreenPulseFirmware/src/MQTTClient.cpp`)
- MQTT broker → MQTT subscriber: delivers telemetry (evidence: `GreenPulseBackend/app/mqtt_client.py`)
- MQTT subscriber → Telemetry database: saves readings (evidence: `GreenPulseBackend/app/mqtt_client.py`)
- MQTT subscriber → Reading model: builds reading (evidence: `GreenPulseBackend/app/mqtt_client.py`)
- MQTT subscriber → WebSocket broadcast: broadcasts readings (evidence: `GreenPulseBackend/app/mqtt_client.py`)
- FastAPI routes → Telemetry database: queries readings (evidence: `GreenPulseBackend/app/main.py`)
- FastAPI routes → Reading model: creates readings (evidence: `GreenPulseBackend/app/main.py`)
- FastAPI routes → EMS orchestration: runs assessment (evidence: `GreenPulseBackend/app/main.py`)
- EMS orchestration → Weather retrieval: fetches weather (evidence: `GreenPulseBackend/app/ems/pipeline.py`)
- EMS orchestration → Air retrieval: fetches air data (evidence: `GreenPulseBackend/app/ems/pipeline.py`)
- Weather retrieval → Open-Meteo services: requests weather
- Air retrieval → Open-Meteo services: requests air data (evidence: `GreenPulseBackend/app/external/open_meteo_air.py`)
- EMS orchestration → Context scoring: scores context (evidence: `GreenPulseBackend/app/ems/pipeline.py`)
- EMS orchestration → AQI calculation: calculates AQI (evidence: `GreenPulseBackend/app/ems/pipeline.py`)
- EMS orchestration → EMS dimensions: calculates dimensions (evidence: `GreenPulseBackend/app/ems/pipeline.py`)
- EMS orchestration → Alert calculation: calculates alert (evidence: `GreenPulseBackend/app/ems/pipeline.py`)
- EMS orchestration → Deterministic playbook: generates playbook (evidence: `GreenPulseBackend/app/ems/pipeline.py`)
- EMS orchestration → LLM advisory: generates advisory (evidence: `GreenPulseBackend/app/ems/pipeline.py`)
- Dashboard user → Dashboard frontend: views dashboard
- Dashboard frontend → FastAPI routes: requests dashboard
