# lungmen-hkm/esp32-gas-leak-sensor architecture

> Architecture diagram of the GitHub repository lungmen-hkm/esp32-gas-leak-sensor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lungmen-hkm/esp32-gas-leak-sensor
- Repository: https://github.com/lungmen-hkm/esp32-gas-leak-sensor

## Overview

This is an ESP-based gas-monitoring system with a Next.js dashboard. Sensor nodes sample gas levels, trigger local alarms above a threshold, and send readings to an API; the dashboard polls that API and displays node readings and online/danger status. The API keeps an in-memory node map and marks nodes offline after a timeout. Firmware and API behavior are supported by sampled source; the dashboard’s polling and rendering are also sampled.

Main entry points: [`app/api/gas-sensor/route.tsx`](https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/app/api/gas-sensor/route.tsx) (Gas sensor API), [`device-firmware/src/main.cpp`](https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/device-firmware/src/main.cpp) (ESP32-C3 node), [`device-firmware-esp8266/src/main.cpp`](https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/device-firmware-esp8266/src/main.cpp) (ESP8266 node), [`app/page.tsx`](https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/app/page.tsx) (Monitoring dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Sensor firmware"]
  node_esp32["ESP32-C3 node<br/>[main.cpp]"]
  node_esp8266["ESP8266 node<br/>[main.cpp]"]
end

subgraph group_backend["Monitoring API"]
  node_sensor_api["Gas sensor API<br/>[route.tsx]"]
  node_device_map[("In-memory device map<br/>[route.tsx]")]
end

subgraph group_dashboard["Web dashboard"]
  node_dashboard["Monitoring dashboard<br/>[page.tsx]"]
end

node_gas_sensor(("MQ2 sensor"))
node_local_alarm["Buzzer and LED"]
node_operator(("Dashboard user"))

node_gas_sensor -->|"provides readings"| node_esp32
node_gas_sensor -->|"provides readings"| node_esp8266
node_esp32 -->|"drives alarm"| node_local_alarm
node_esp8266 -->|"drives alarm"| node_local_alarm
node_esp32 -->|"POST readings"| node_sensor_api
node_esp8266 -->|"POST readings"| node_sensor_api
node_sensor_api -->|"writes device state"| node_device_map
node_device_map -->|"reads device state"| node_sensor_api
node_dashboard -->|"polls nodes"| node_sensor_api
node_sensor_api -->|"returns node status"| node_dashboard
node_dashboard -->|"displays status"| node_operator

click node_esp32 "https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/device-firmware/src/main.cpp"
click node_esp8266 "https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/device-firmware-esp8266/src/main.cpp"
click node_sensor_api "https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/app/api/gas-sensor/route.tsx"
click node_device_map "https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/app/api/gas-sensor/route.tsx"
click node_dashboard "https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/app/page.tsx"

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_esp32,node_esp8266,node_operator toneBlue
class node_sensor_api,node_device_map toneAmber
class node_dashboard toneMint
class node_gas_sensor,node_local_alarm toneIndigo
```

## Components

### Sensor firmware

- [ESP32-C3 node](https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/device-firmware/src/main.cpp): `device-firmware/src/main.cpp`
- [ESP8266 node](https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/device-firmware-esp8266/src/main.cpp): `device-firmware-esp8266/src/main.cpp`

### Monitoring API

- [Gas sensor API](https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/app/api/gas-sensor/route.tsx): `app/api/gas-sensor/route.tsx`
- [In-memory device map](https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/app/api/gas-sensor/route.tsx): `app/api/gas-sensor/route.tsx`

### Web dashboard

- [Monitoring dashboard](https://github.com/lungmen-hkm/esp32-gas-leak-sensor/blob/master/app/page.tsx): `app/page.tsx`

### Other components

- **MQ2 sensor**
- **Buzzer and LED**
- **Dashboard user**

## Connections

- MQ2 sensor → ESP32-C3 node: provides readings
- MQ2 sensor → ESP8266 node: provides readings
- ESP32-C3 node → Buzzer and LED: drives alarm
- ESP8266 node → Buzzer and LED: drives alarm
- ESP32-C3 node → Gas sensor API: POST readings
- ESP8266 node → Gas sensor API: POST readings
- Gas sensor API → In-memory device map: writes device state
- In-memory device map → Gas sensor API: reads device state
- Monitoring dashboard → Gas sensor API: polls nodes
- Gas sensor API → Monitoring dashboard: returns node status
- Monitoring dashboard → Dashboard user: displays status