# tharun-debug2006/aqi architecture

> Architecture diagram of the GitHub repository tharun-debug2006/aqi, 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/tharun-debug2006/aqi
- Repository: https://github.com/tharun-debug2006/aqi

## Overview

SmartAQI is a Bengaluru-focused air-quality forecasting and personalized health-advisory application. Its documented offline workflow audits and preprocesses station history, engineers forecasting features, trains and evaluates pollutant models, then presents forecasts and alerts in a Streamlit dashboard. AQI calculation, coverage/locality analysis, historical trends, and Open-Meteo estimates are additional product capabilities. The dashboard, forecasting, and alert implementations were not sampled, so their connections are documented or marked unverified rather than inferred from imports.

Main entry points: [`dashboard/app.py`](https://github.com/tharun-debug2006/aqi/blob/main/dashboard/app.py) (Streamlit dashboard), [`src/smartaqi/models/train_main.py`](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/models/train_main.py) (Model training), [`src/smartaqi/preprocessing/clean.py`](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/preprocessing/clean.py) (Clean and merge), [`Data/processed/all_stations_hourly.parquet`](https://github.com/tharun-debug2006/aqi/blob/main/Data/processed/all_stations_hourly.parquet) (Hourly dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_raw["Station history"]
  node_audit["Coverage audit<br/>[audit_data.py]"]
  node_loaders["Historical loaders<br/>[loaders.py]"]
  node_clean["Clean and merge<br/>[clean.py]"]
  node_processed["Hourly dataset"]
  node_localities["Locality coverage<br/>[clean.py]"]
  node_reports["Audit and metrics"]
end

subgraph group_prediction["AQI and prediction"]
  node_features["Forecast features<br/>[build.py]"]
  node_trainer["Model training<br/>[train_main.py]"]
  node_evaluation["Model evaluation<br/>[train.py]"]
  node_saved["Trained models"]
  node_forecast["Forecast generation"]
  node_aqi["CPCB AQI<br/>[compute.py]"]
end

subgraph group_advisories["Health advisories"]
  node_alerts["Health advisories<br/>[engine.py]"]
end

subgraph group_application["Dashboard and integrations"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
  node_openmeteo["Open-Meteo data"]
  node_config["Product configuration<br/>[config.yaml]"]
end

node_user(("Bengaluru user"))
node_service["Open-Meteo"]

node_user -->|"views"| node_dashboard
node_raw -->|"audits"| node_audit
node_raw -->|"loads"| node_loaders
node_loaders -->|"loads via"| node_clean
node_clean -->|"writes"| node_processed
node_clean -->|"assesses"| node_localities
node_audit -->|"produces"| node_reports
node_processed -->|"builds from"| node_features
node_features -->|"provides features"| node_trainer
node_trainer -->|"trains and evaluates"| node_evaluation
node_trainer -->|"persists"| node_saved
node_trainer -->|"writes comparison"| node_reports
node_saved -.->|"predicts with"| node_forecast
node_forecast -.->|"displays"| node_dashboard
node_processed -.->|"computes from"| node_aqi
node_aqi -.->|"displays"| node_dashboard
node_forecast -.->|"informs"| node_alerts
node_alerts -.->|"displays"| node_dashboard
node_service -.->|"serves estimates"| node_openmeteo
node_openmeteo -.->|"shows estimates"| node_dashboard
node_config -->|"sets thresholds"| node_localities
node_config -->|"sets thresholds"| node_alerts

click node_raw "https://github.com/tharun-debug2006/aqi/tree/main/Data/raw"
click node_audit "https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/data_ingestion/audit_data.py"
click node_loaders "https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/data_ingestion/loaders.py"
click node_clean "https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/preprocessing/clean.py"
click node_processed "https://github.com/tharun-debug2006/aqi/blob/main/Data/processed/all_stations_hourly.parquet"
click node_localities "https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/preprocessing/clean.py"
click node_features "https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/features/build.py"
click node_trainer "https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/models/train_main.py"
click node_evaluation "https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/models/train.py"
click node_saved "https://github.com/tharun-debug2006/aqi/tree/main/models"
click node_forecast "https://github.com/tharun-debug2006/aqi/tree/main/src/smartaqi/forecasting"
click node_aqi "https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/aqi/compute.py"
click node_alerts "https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/alerts/engine.py"
click node_dashboard "https://github.com/tharun-debug2006/aqi/blob/main/dashboard/app.py"
click node_openmeteo "https://github.com/tharun-debug2006/aqi/tree/main/src/smartaqi/data_ingestion"
click node_config "https://github.com/tharun-debug2006/aqi/blob/main/config.yaml"
click node_reports "https://github.com/tharun-debug2006/aqi/tree/main/reports"

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_raw,node_audit,node_loaders,node_clean,node_processed,node_localities,node_reports,node_user toneBlue
class node_features,node_trainer,node_evaluation,node_saved,node_forecast,node_aqi toneAmber
class node_alerts toneMint
class node_dashboard,node_openmeteo,node_config toneRose
class node_service toneIndigo
```

## Components

### Data preparation

- [Station history](https://github.com/tharun-debug2006/aqi/tree/main/Data/raw): `Data/raw`
- [Coverage audit](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/data_ingestion/audit_data.py): `src/smartaqi/data_ingestion/audit_data.py`
- [Historical loaders](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/data_ingestion/loaders.py): `src/smartaqi/data_ingestion/loaders.py`
- [Clean and merge](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/preprocessing/clean.py): `src/smartaqi/preprocessing/clean.py`
- [Hourly dataset](https://github.com/tharun-debug2006/aqi/blob/main/Data/processed/all_stations_hourly.parquet): `Data/processed/all_stations_hourly.parquet`
- [Locality coverage](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/preprocessing/clean.py): `src/smartaqi/preprocessing/clean.py`
- [Audit and metrics](https://github.com/tharun-debug2006/aqi/tree/main/reports): `reports`

### AQI and prediction

- [Forecast features](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/features/build.py): `src/smartaqi/features/build.py`
- [Model training](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/models/train_main.py): `src/smartaqi/models/train_main.py`
- [Model evaluation](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/models/train.py): `src/smartaqi/models/train.py`
- [Trained models](https://github.com/tharun-debug2006/aqi/tree/main/models): `models`
- [Forecast generation](https://github.com/tharun-debug2006/aqi/tree/main/src/smartaqi/forecasting): `src/smartaqi/forecasting`
- [CPCB AQI](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/aqi/compute.py): `src/smartaqi/aqi/compute.py`

### Health advisories

- [Health advisories](https://github.com/tharun-debug2006/aqi/blob/main/src/smartaqi/alerts/engine.py): `src/smartaqi/alerts/engine.py`

### Dashboard and integrations

- [Streamlit dashboard](https://github.com/tharun-debug2006/aqi/blob/main/dashboard/app.py): `dashboard/app.py`
- [Open-Meteo data](https://github.com/tharun-debug2006/aqi/tree/main/src/smartaqi/data_ingestion): `src/smartaqi/data_ingestion`
- [Product configuration](https://github.com/tharun-debug2006/aqi/blob/main/config.yaml): `config.yaml`

### Other components

- **Bengaluru user**
- **Open-Meteo**

## Connections

- Bengaluru user → Streamlit dashboard: views (evidence: `README.md`)
- Station history → Coverage audit: audits (evidence: `README.md`)
- Station history → Historical loaders: loads (evidence: `README.md`)
- Historical loaders → Clean and merge: loads via (evidence: `src/smartaqi/preprocessing/clean.py`)
- Clean and merge → Hourly dataset: writes (evidence: `README.md`)
- Clean and merge → Locality coverage: assesses (evidence: `src/smartaqi/preprocessing/clean.py`)
- Coverage audit → Audit and metrics: produces (evidence: `README.md`)
- Hourly dataset → Forecast features: builds from (evidence: `README.md`)
- Forecast features → Model training: provides features (evidence: `src/smartaqi/models/train_main.py`)
- Model training → Model evaluation: trains and evaluates (evidence: `src/smartaqi/models/train_main.py`)
- Model training → Trained models: persists (evidence: `README.md`)
- Model training → Audit and metrics: writes comparison (evidence: `README.md`)
- Trained models → Forecast generation: predicts with
- Forecast generation → Streamlit dashboard: displays
- Hourly dataset → CPCB AQI: computes from
- CPCB AQI → Streamlit dashboard: displays
- Forecast generation → Health advisories: informs
- Health advisories → Streamlit dashboard: displays
- Open-Meteo → Open-Meteo data: serves estimates (evidence: `README.md`)
- Open-Meteo data → Streamlit dashboard: shows estimates (evidence: `README.md`)
- Product configuration → Locality coverage: sets thresholds (evidence: `README.md`)
- Product configuration → Health advisories: sets thresholds (evidence: `README.md`)
