# aseemprasad/air-quality-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/aseemprasad/air-quality-intelligence
- Repository: https://github.com/aseemprasad/air-quality-intelligence

## Overview

This is a local-first air-quality monitoring and forecasting platform. Its principal workflow collects OpenAQ observations and Open-Meteo weather, parses and deduplicates records, stores them as partitioned Parquet, and uses quality checks and analytics to support anomaly/event detection and forecasting. Results are exposed through a FastAPI service. The graph also includes the documented control-plane database and the main intelligence capabilities. Some analytics, quality, and serving links are based on README architecture statements; their implementation details were not sampled.

Main entry points: [`src/aq_engine/ingestion/orchestrator.py`](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ingestion/orchestrator.py) (Ingestion orchestration), [`src/aq_engine/api/main.py`](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/api/main.py) (FastAPI application), [`src/aq_engine/storage/parquet_io.py`](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/storage/parquet_io.py) (Partitioned Parquet), [`src/aq_engine/connectors/openaq.py`](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/connectors/openaq.py) (Air-quality connector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion"]
  node_ingestion["Ingestion orchestration<br/>[orchestrator.py]"]
  node_openaq_connector["Air-quality connector<br/>[openaq.py]"]
  node_weather_connector["Weather connector<br/>[open_meteo.py]"]
  node_connector_base["Connector framework<br/>[base.py]"]
  node_connector_models["Canonical record models<br/>[models.py]"]
end

subgraph group_quality_storage["Quality &amp; Storage"]
  node_quality_contracts["Record contracts<br/>[contracts.py]"]
  node_deduplication["Deduplication &amp; hashing<br/>[deduplication.py]"]
  node_quality_rules["Quality rules<br/>[rules.py]"]
  node_quality_validator["Record validation<br/>[validator.py]"]
  node_quarantine["Quarantine<br/>[quarantine.py]"]
  node_parquet[("Partitioned Parquet<br/>[parquet_io.py]")]
end

subgraph group_intelligence["Intelligence"]
  node_aggregation["Hourly / daily aggregation<br/>[aggregation.py]"]
  node_baselines["Historical baselines<br/>[baselines.py]"]
  node_anomaly["Anomaly detection<br/>[anomaly.py]"]
  node_events["Pollution events<br/>[events.py]"]
  node_station_health["Station health<br/>[station_health.py]"]
  node_features["Forecast features<br/>[features.py]"]
  node_training["Model training<br/>[training.py]"]
  node_ml_baselines["Forecast baselines<br/>[baselines.py]"]
  node_inference["Forecast inference<br/>[inference.py]"]
end

subgraph group_serving_control["Serving &amp; Control"]
  node_control_db[("Control-plane database<br/>[db.py]")]
  node_api["FastAPI application<br/>[main.py]"]
  node_observations_api["Observation endpoints<br/>[observations.py]"]
end

node_operator(("Operator / scheduler"))
node_openaq_service(("OpenAQ"))
node_weather_service(("Open-Meteo"))

node_operator -->|"triggers"| node_ingestion
node_ingestion -->|"initializes"| node_openaq_connector
node_ingestion -->|"initializes"| node_weather_connector
node_openaq_connector -->|"fetches data"| node_openaq_service
node_weather_connector -->|"fetches data"| node_weather_service
node_openaq_connector -->|"inherits"| node_connector_base
node_weather_connector -->|"inherits"| node_connector_base
node_openaq_connector -->|"parses into"| node_connector_models
node_weather_connector -->|"parses into"| node_connector_models
node_ingestion -->|"deduplicates"| node_deduplication
node_ingestion -->|"writes records"| node_parquet
node_ingestion -->|"records run state"| node_control_db
node_ingestion -->|"uses contracts"| node_quality_contracts
node_deduplication -->|"reads records"| node_parquet
node_quality_validator -->|"applies"| node_quality_rules
node_parquet -.->|"validated by"| node_quality_validator
node_quality_validator -.->|"routes rejects"| node_quarantine
node_parquet -->|"transforms"| node_aggregation
node_aggregation -.->|"supports"| node_baselines
node_aggregation -->|"analyzes"| node_anomaly
node_anomaly -.->|"identifies events"| node_events
node_aggregation -.->|"informs health"| node_station_health
node_parquet -->|"builds features"| node_features
node_features -->|"trains on"| node_training
node_features -->|"provides features"| node_inference
node_training -->|"provides model"| node_inference
node_ml_baselines -->|"fallback predictions"| node_inference
node_api -->|"registers router"| node_observations_api
node_operator -->|"requests results"| node_api
node_api -.->|"serves forecasts"| node_inference
node_api -.->|"serves events"| node_events
node_api -.->|"serves context"| node_anomaly
node_api -.->|"checks health"| node_control_db

click node_ingestion "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ingestion/orchestrator.py"
click node_openaq_connector "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/connectors/openaq.py"
click node_weather_connector "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/connectors/open_meteo.py"
click node_connector_base "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/connectors/base.py"
click node_connector_models "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/connectors/models.py"
click node_quality_contracts "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/quality/contracts.py"
click node_deduplication "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/quality/deduplication.py"
click node_quality_rules "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/quality/rules.py"
click node_quality_validator "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/quality/validator.py"
click node_quarantine "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/quality/quarantine.py"
click node_parquet "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/storage/parquet_io.py"
click node_control_db "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/storage/db.py"
click node_aggregation "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/analytics/aggregation.py"
click node_baselines "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/analytics/baselines.py"
click node_anomaly "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/analytics/anomaly.py"
click node_events "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/analytics/events.py"
click node_station_health "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/analytics/station_health.py"
click node_features "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ml/features.py"
click node_training "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ml/training.py"
click node_ml_baselines "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ml/baselines.py"
click node_inference "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ml/inference.py"
click node_api "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/api/main.py"
click node_observations_api "https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/api/observations.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_ingestion,node_openaq_connector,node_weather_connector,node_connector_base,node_connector_models toneBlue
class node_quality_contracts,node_deduplication,node_quality_rules,node_quality_validator,node_quarantine,node_parquet toneAmber
class node_aggregation,node_baselines,node_anomaly,node_events,node_station_health,node_features,node_training,node_ml_baselines,node_inference toneMint
class node_control_db,node_api,node_observations_api,node_operator toneRose
class node_openaq_service,node_weather_service toneIndigo
```

## Components

### Ingestion

- [Ingestion orchestration](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ingestion/orchestrator.py): `src/aq_engine/ingestion/orchestrator.py`
- [Air-quality connector](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/connectors/openaq.py): `src/aq_engine/connectors/openaq.py`
- [Weather connector](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/connectors/open_meteo.py): `src/aq_engine/connectors/open_meteo.py`
- [Connector framework](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/connectors/base.py): `src/aq_engine/connectors/base.py`
- [Canonical record models](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/connectors/models.py): `src/aq_engine/connectors/models.py`

### Quality & Storage

- [Record contracts](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/quality/contracts.py): `src/aq_engine/quality/contracts.py`
- [Deduplication & hashing](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/quality/deduplication.py): `src/aq_engine/quality/deduplication.py`
- [Quality rules](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/quality/rules.py): `src/aq_engine/quality/rules.py`
- [Record validation](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/quality/validator.py): `src/aq_engine/quality/validator.py`
- [Quarantine](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/quality/quarantine.py): `src/aq_engine/quality/quarantine.py`
- [Partitioned Parquet](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/storage/parquet_io.py): `src/aq_engine/storage/parquet_io.py`

### Intelligence

- [Hourly / daily aggregation](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/analytics/aggregation.py): `src/aq_engine/analytics/aggregation.py`
- [Historical baselines](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/analytics/baselines.py): `src/aq_engine/analytics/baselines.py`
- [Anomaly detection](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/analytics/anomaly.py): `src/aq_engine/analytics/anomaly.py`
- [Pollution events](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/analytics/events.py): `src/aq_engine/analytics/events.py`
- [Station health](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/analytics/station_health.py): `src/aq_engine/analytics/station_health.py`
- [Forecast features](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ml/features.py): `src/aq_engine/ml/features.py`
- [Model training](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ml/training.py): `src/aq_engine/ml/training.py`
- [Forecast baselines](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ml/baselines.py): `src/aq_engine/ml/baselines.py`
- [Forecast inference](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/ml/inference.py): `src/aq_engine/ml/inference.py`

### Serving & Control

- [Control-plane database](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/storage/db.py): `src/aq_engine/storage/db.py`
- [FastAPI application](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/api/main.py): `src/aq_engine/api/main.py`
- [Observation endpoints](https://github.com/aseemprasad/air-quality-intelligence/blob/main/src/aq_engine/api/observations.py): `src/aq_engine/api/observations.py`

### Other components

- **Operator / scheduler**
- **OpenAQ**
- **Open-Meteo**

## Connections

- Operator / scheduler → Ingestion orchestration: triggers
- Ingestion orchestration → Air-quality connector: initializes (evidence: `src/aq_engine/ingestion/orchestrator.py`)
- Ingestion orchestration → Weather connector: initializes (evidence: `src/aq_engine/ingestion/orchestrator.py`)
- Air-quality connector → OpenAQ: fetches data (evidence: `src/aq_engine/connectors/openaq.py`)
- Weather connector → Open-Meteo: fetches data (evidence: `src/aq_engine/connectors/open_meteo.py`)
- Air-quality connector → Connector framework: inherits (evidence: `src/aq_engine/connectors/openaq.py`)
- Weather connector → Connector framework: inherits (evidence: `src/aq_engine/connectors/open_meteo.py`)
- Air-quality connector → Canonical record models: parses into (evidence: `src/aq_engine/connectors/openaq.py`)
- Weather connector → Canonical record models: parses into (evidence: `src/aq_engine/connectors/open_meteo.py`)
- Ingestion orchestration → Deduplication & hashing: deduplicates (evidence: `src/aq_engine/ingestion/orchestrator.py`)
- Ingestion orchestration → Partitioned Parquet: writes records (evidence: `src/aq_engine/ingestion/orchestrator.py`)
- Ingestion orchestration → Control-plane database: records run state (evidence: `src/aq_engine/ingestion/orchestrator.py`)
- Ingestion orchestration → Record contracts: uses contracts (evidence: `src/aq_engine/ingestion/orchestrator.py`)
- Deduplication & hashing → Partitioned Parquet: reads records (evidence: `src/aq_engine/quality/deduplication.py`)
- Record validation → Quality rules: applies (evidence: `src/aq_engine/quality/validator.py`)
- Partitioned Parquet → Record validation: validated by
- Record validation → Quarantine: routes rejects
- Partitioned Parquet → Hourly / daily aggregation: transforms (evidence: `README.md`)
- Hourly / daily aggregation → Historical baselines: supports
- Hourly / daily aggregation → Anomaly detection: analyzes (evidence: `README.md`)
- Anomaly detection → Pollution events: identifies events
- Hourly / daily aggregation → Station health: informs health
- Partitioned Parquet → Forecast features: builds features (evidence: `README.md`)
- Forecast features → Model training: trains on (evidence: `README.md`)
- Forecast features → Forecast inference: provides features (evidence: `src/aq_engine/ml/inference.py`)
- Model training → Forecast inference: provides model (evidence: `src/aq_engine/ml/inference.py`)
- Forecast baselines → Forecast inference: fallback predictions (evidence: `src/aq_engine/ml/inference.py`)
- FastAPI application → Observation endpoints: registers router (evidence: `src/aq_engine/api/main.py`)
- Operator / scheduler → FastAPI application: requests results (evidence: `README.md`)
- FastAPI application → Forecast inference: serves forecasts
- FastAPI application → Pollution events: serves events (evidence: `README.md`)
- FastAPI application → Anomaly detection: serves context (evidence: `README.md`)
- FastAPI application → Control-plane database: checks health
