# lhg96/airquality-platform architecture

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

- Interactive diagram: https://gitdiagram.com/lhg96/airquality-platform
- Repository: https://github.com/lhg96/airquality-platform

## Overview

This repository describes an air-quality platform spanning sensor measurement, public-data collection, serial acquisition, calibration, an API, and a demo dashboard. The README documents the main data path and the demo’s mock/live modes; the only sampled source is the device header, so device internals and the Java subsystems are represented at the documented subsystem level rather than as inferred call graphs.

Main entry points: [`demo/main.py`](https://github.com/lhg96/airquality-platform/blob/main/demo/main.py) (Demo server), [`air-quality-api`](https://github.com/lhg96/airquality-platform/tree/main/air-quality-api) (REST API server), [`air-quality-device/RA200_v1.3/RA200_v1.3.ino`](https://github.com/lhg96/airquality-platform/blob/main/air-quality-device/RA200_v1.3/RA200_v1.3.ino) (ESP32 RA200), [`air-quality-calibration`](https://github.com/lhg96/airquality-platform/tree/main/air-quality-calibration) (Data calibration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["Device sensing"]
  node_device["ESP32 RA200<br/>[RA200_v1.3.ino]"]
  node_sensor_state["Sensor state<br/>[RA100.h]"]
  node_device_filter["Device filtering<br/>[Filter.ino]"]
end

subgraph group_collection["Data collection"]
  node_serial["Serial acquisition"]
  node_crawler["AirKorea crawler"]
end

subgraph group_processing["Calibration"]
  node_calibration["Data calibration"]
end

subgraph group_service["API service"]
  node_api["REST API server"]
  node_api_storage[("Air-quality storage")]
end

subgraph group_demo["Demo dashboard"]
  node_demo_server["Demo server<br/>[main.py]"]
  node_mock_data["Mock data generator<br/>[mock_data.py]"]
  node_live_client["Live API client<br/>[api_client.py]"]
  node_dashboard["Dashboard UI<br/>[app.js]"]
end

node_operator(("Operator"))
node_airkorea["AirKorea API"]
node_api_clients["API clients"]

node_device -->|"updates readings"| node_sensor_state
node_device -->|"filters readings"| node_device_filter
node_device -->|"streams serial data"| node_serial
node_airkorea -->|"provides measurements"| node_crawler
node_serial -->|"supplies sensor data"| node_calibration
node_crawler -->|"supplies collected data"| node_calibration
node_calibration -->|"provides processed data"| node_api
node_api -->|"stores and retrieves"| node_api_storage
node_api_clients -->|"uses endpoints"| node_api
node_operator -->|"opens dashboard"| node_demo_server
node_demo_server -->|"generates demo data"| node_mock_data
node_demo_server -.->|"proxies live requests"| node_live_client
node_live_client -->|"requests live data"| node_api
node_demo_server -->|"serves dashboard"| node_dashboard

click node_device "https://github.com/lhg96/airquality-platform/blob/main/air-quality-device/RA200_v1.3/RA200_v1.3.ino"
click node_sensor_state "https://github.com/lhg96/airquality-platform/blob/main/air-quality-device/RA200_v1.3/RA100.h"
click node_device_filter "https://github.com/lhg96/airquality-platform/blob/main/air-quality-device/RA200_v1.3/Filter.ino"
click node_serial "https://github.com/lhg96/airquality-platform/tree/main/air-quality-serial"
click node_crawler "https://github.com/lhg96/airquality-platform/tree/main/air-quality-crawler"
click node_calibration "https://github.com/lhg96/airquality-platform/tree/main/air-quality-calibration"
click node_api "https://github.com/lhg96/airquality-platform/tree/main/air-quality-api"
click node_api_storage "https://github.com/lhg96/airquality-platform/tree/main/air-quality-api"
click node_api_clients "https://github.com/lhg96/airquality-platform/tree/main/air-quality-client"
click node_demo_server "https://github.com/lhg96/airquality-platform/blob/main/demo/main.py"
click node_mock_data "https://github.com/lhg96/airquality-platform/blob/main/demo/mock_data.py"
click node_live_client "https://github.com/lhg96/airquality-platform/blob/main/demo/api_client.py"
click node_dashboard "https://github.com/lhg96/airquality-platform/blob/main/demo/static/app.js"

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_device,node_sensor_state,node_device_filter,node_api_clients toneBlue
class node_serial,node_crawler toneAmber
class node_calibration,node_airkorea toneMint
class node_api,node_api_storage toneRose
class node_demo_server,node_mock_data,node_live_client,node_dashboard,node_operator toneIndigo
```

## Components

### Device sensing

- [ESP32 RA200](https://github.com/lhg96/airquality-platform/blob/main/air-quality-device/RA200_v1.3/RA200_v1.3.ino): `air-quality-device/RA200_v1.3/RA200_v1.3.ino`
- [Sensor state](https://github.com/lhg96/airquality-platform/blob/main/air-quality-device/RA200_v1.3/RA100.h): `air-quality-device/RA200_v1.3/RA100.h`
- [Device filtering](https://github.com/lhg96/airquality-platform/blob/main/air-quality-device/RA200_v1.3/Filter.ino): `air-quality-device/RA200_v1.3/Filter.ino`

### Data collection

- [Serial acquisition](https://github.com/lhg96/airquality-platform/tree/main/air-quality-serial): `air-quality-serial`
- [AirKorea crawler](https://github.com/lhg96/airquality-platform/tree/main/air-quality-crawler): `air-quality-crawler`

### Calibration

- [Data calibration](https://github.com/lhg96/airquality-platform/tree/main/air-quality-calibration): `air-quality-calibration`

### API service

- [REST API server](https://github.com/lhg96/airquality-platform/tree/main/air-quality-api): `air-quality-api`
- [Air-quality storage](https://github.com/lhg96/airquality-platform/tree/main/air-quality-api): `air-quality-api`

### Demo dashboard

- [Demo server](https://github.com/lhg96/airquality-platform/blob/main/demo/main.py): `demo/main.py`
- [Mock data generator](https://github.com/lhg96/airquality-platform/blob/main/demo/mock_data.py): `demo/mock_data.py`
- [Live API client](https://github.com/lhg96/airquality-platform/blob/main/demo/api_client.py): `demo/api_client.py`
- [Dashboard UI](https://github.com/lhg96/airquality-platform/blob/main/demo/static/app.js): `demo/static/app.js`

### Other components

- **Operator**
- **AirKorea API**
- [API clients](https://github.com/lhg96/airquality-platform/tree/main/air-quality-client): `air-quality-client`

## Connections

- ESP32 RA200 → Sensor state: updates readings (evidence: `README.md`)
- ESP32 RA200 → Device filtering: filters readings (evidence: `README.md`)
- ESP32 RA200 → Serial acquisition: streams serial data (evidence: `README.md`)
- AirKorea API → AirKorea crawler: provides measurements (evidence: `README.md`)
- Serial acquisition → Data calibration: supplies sensor data (evidence: `README.md`)
- AirKorea crawler → Data calibration: supplies collected data (evidence: `README.md`)
- Data calibration → REST API server: provides processed data (evidence: `README.md`)
- REST API server → Air-quality storage: stores and retrieves (evidence: `README.md`)
- API clients → REST API server: uses endpoints (evidence: `README.md`)
- Operator → Demo server: opens dashboard (evidence: `README.md`)
- Demo server → Mock data generator: generates demo data (evidence: `README.md`)
- Demo server → Live API client: proxies live requests (evidence: `README.md`)
- Live API client → REST API server: requests live data (evidence: `README.md`)
- Demo server → Dashboard UI: serves dashboard (evidence: `README.md`)