# adithya0622/delhi-model architecture

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

- Interactive diagram: https://gitdiagram.com/adithya0622/delhi-model
- Repository: https://github.com/adithya0622/delhi-model

## Overview

Delhi NCR AQI Forecasting System provides a 72-hour coupled air-quality forecast and a live operator console. The main workflow gathers meteorology, fire detections and station observations; models inversion and aerosol feedback in a single-column forecast; converts concentrations to AQI; and serves forecast, plume and live-condition views. The repository also includes exposure, source-apportionment, validation and alert capabilities. Relationships use the README and sampled call sites; unsampled routes and service internals are represented only where their paths and roles are documented.

Main entry points: [`backend/app/services/aqi_service.py`](https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/aqi_service.py) (AQI forecast integrator), [`webapp/src/App.tsx`](https://github.com/adithya0622/delhi-model/blob/main/webapp/src/App.tsx) (React console), [`backend/app/api/v1/endpoints.py`](https://github.com/adithya0622/delhi-model/blob/main/backend/app/api/v1/endpoints.py) (Versioned routes), [`backend/app/main.py`](https://github.com/adithya0622/delhi-model/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Operator interfaces"]
  node_console["React console<br/>[App.tsx]"]
  node_forecast_hook["Forecast data hook<br/>[useForecastData.ts]"]
  node_streamlit["Streamlit dashboard<br/>[app.py]"]
  node_api_client["Frontend API client<br/>[api.ts]"]
end

subgraph group_api["API delivery"]
  node_app["FastAPI application<br/>[main.py]"]
  node_routes["Versioned routes<br/>[endpoints.py]"]
  node_ml_routes["ML forecast routes"]
  node_chronos_routes["Chronos routes"]
  node_backtest_routes["Backtest routes"]
end

subgraph group_forecast["Forecast physics"]
  node_aqi["AQI forecast integrator<br/>[aqi_service.py]"]
  node_inversion["Inversion physics"]
  node_column["Column model<br/>[box_model.py]"]
  node_plume["Plume transport<br/>[plume_advection.py]"]
  node_weather["Weather providers"]
end

subgraph group_observations["Live observations"]
  node_stations["Realtime stations"]
  node_consensus["Consensus service"]
end

subgraph group_insights["User insights"]
  node_alerts["Alert evaluation<br/>[alertsEngine.ts]"]
  node_exposure["Exposure service"]
  node_emissions["Source apportionment"]
  node_clinical["Clinical assistant<br/>[clinicalEngine.ts]"]
  node_backtest["Backtest service"]
end

node_operator(("Operator"))
node_openaq(("OpenAQ"))
node_firms(("NASA FIRMS"))
node_openmeteo(("Open-Meteo"))

node_operator -->|"uses"| node_console
node_operator -->|"uses"| node_streamlit
node_console -->|"loads data"| node_forecast_hook
node_forecast_hook -->|"requests"| node_api_client
node_api_client -->|"calls API"| node_app
node_streamlit -->|"requests"| node_app
node_app -->|"mounts router"| node_routes
node_routes -->|"serves forecast"| node_aqi
node_routes -->|"serves readings"| node_stations
node_routes -->|"collects consensus"| node_consensus
node_ml_routes -->|"forecast basis"| node_aqi
node_chronos_routes -.->|"forecast context"| node_aqi
node_backtest_routes -->|"runs backtest"| node_backtest
node_aqi -->|"gets meteorology"| node_weather
node_weather -->|"fetches weather"| node_openmeteo
node_aqi -->|"computes feedback"| node_inversion
node_aqi -->|"integrates mass"| node_column
node_aqi -->|"couples plume"| node_plume
node_plume -->|"gets detections"| node_firms
node_stations -->|"fetches readings"| node_openaq
node_routes -->|"calculates exposure"| node_exposure
node_routes -->|"calculates sources"| node_emissions
node_console -->|"evaluates alerts"| node_alerts
node_console -->|"offers guidance"| node_clinical
node_console -->|"requests exposure"| node_exposure
node_console -->|"requests attribution"| node_emissions

click node_console "https://github.com/adithya0622/delhi-model/blob/main/webapp/src/App.tsx"
click node_forecast_hook "https://github.com/adithya0622/delhi-model/blob/main/webapp/src/hooks/useForecastData.ts"
click node_streamlit "https://github.com/adithya0622/delhi-model/blob/main/frontend/app.py"
click node_api_client "https://github.com/adithya0622/delhi-model/blob/main/webapp/src/lib/api.ts"
click node_app "https://github.com/adithya0622/delhi-model/blob/main/backend/app/main.py"
click node_routes "https://github.com/adithya0622/delhi-model/blob/main/backend/app/api/v1/endpoints.py"
click node_ml_routes "https://github.com/adithya0622/delhi-model/blob/main/backend/app/api/v1/ml_forecast_endpoint.py"
click node_chronos_routes "https://github.com/adithya0622/delhi-model/blob/main/backend/app/api/v1/chronos_endpoint.py"
click node_backtest_routes "https://github.com/adithya0622/delhi-model/blob/main/backend/app/api/v1/backtest_endpoint.py"
click node_aqi "https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/aqi_service.py"
click node_inversion "https://github.com/adithya0622/delhi-model/blob/main/backend/app/physics/inversion_engine.py"
click node_column "https://github.com/adithya0622/delhi-model/blob/main/backend/app/physics/box_model.py"
click node_plume "https://github.com/adithya0622/delhi-model/blob/main/backend/app/physics/plume_advection.py"
click node_weather "https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/weather_providers.py"
click node_stations "https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/realtime_service.py"
click node_consensus "https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/consensus_service.py"
click node_alerts "https://github.com/adithya0622/delhi-model/blob/main/webapp/src/lib/alertsEngine.ts"
click node_exposure "https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/exposure_service.py"
click node_emissions "https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/emission_service.py"
click node_clinical "https://github.com/adithya0622/delhi-model/blob/main/webapp/src/lib/clinicalEngine.ts"
click node_backtest "https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/backtest_service.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_console,node_forecast_hook,node_streamlit,node_api_client toneBlue
class node_app,node_routes,node_ml_routes,node_chronos_routes,node_backtest_routes toneAmber
class node_aqi,node_inversion,node_column,node_plume,node_weather toneMint
class node_stations,node_consensus toneRose
class node_alerts,node_exposure,node_emissions,node_clinical,node_backtest,node_operator,node_openaq,node_firms,node_openmeteo toneIndigo
```

## Components

### Operator interfaces

- [React console](https://github.com/adithya0622/delhi-model/blob/main/webapp/src/App.tsx): `webapp/src/App.tsx`
- [Forecast data hook](https://github.com/adithya0622/delhi-model/blob/main/webapp/src/hooks/useForecastData.ts): `webapp/src/hooks/useForecastData.ts`
- [Streamlit dashboard](https://github.com/adithya0622/delhi-model/blob/main/frontend/app.py): `frontend/app.py`
- [Frontend API client](https://github.com/adithya0622/delhi-model/blob/main/webapp/src/lib/api.ts): `webapp/src/lib/api.ts`

### API delivery

- [FastAPI application](https://github.com/adithya0622/delhi-model/blob/main/backend/app/main.py): `backend/app/main.py`
- [Versioned routes](https://github.com/adithya0622/delhi-model/blob/main/backend/app/api/v1/endpoints.py): `backend/app/api/v1/endpoints.py`
- [ML forecast routes](https://github.com/adithya0622/delhi-model/blob/main/backend/app/api/v1/ml_forecast_endpoint.py): `backend/app/api/v1/ml_forecast_endpoint.py`
- [Chronos routes](https://github.com/adithya0622/delhi-model/blob/main/backend/app/api/v1/chronos_endpoint.py): `backend/app/api/v1/chronos_endpoint.py`
- [Backtest routes](https://github.com/adithya0622/delhi-model/blob/main/backend/app/api/v1/backtest_endpoint.py): `backend/app/api/v1/backtest_endpoint.py`

### Forecast physics

- [AQI forecast integrator](https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/aqi_service.py): `backend/app/services/aqi_service.py`
- [Inversion physics](https://github.com/adithya0622/delhi-model/blob/main/backend/app/physics/inversion_engine.py): `backend/app/physics/inversion_engine.py`
- [Column model](https://github.com/adithya0622/delhi-model/blob/main/backend/app/physics/box_model.py): `backend/app/physics/box_model.py`
- [Plume transport](https://github.com/adithya0622/delhi-model/blob/main/backend/app/physics/plume_advection.py): `backend/app/physics/plume_advection.py`
- [Weather providers](https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/weather_providers.py): `backend/app/services/weather_providers.py`

### Live observations

- [Realtime stations](https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/realtime_service.py): `backend/app/services/realtime_service.py`
- [Consensus service](https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/consensus_service.py): `backend/app/services/consensus_service.py`

### User insights

- [Alert evaluation](https://github.com/adithya0622/delhi-model/blob/main/webapp/src/lib/alertsEngine.ts): `webapp/src/lib/alertsEngine.ts`
- [Exposure service](https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/exposure_service.py): `backend/app/services/exposure_service.py`
- [Source apportionment](https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/emission_service.py): `backend/app/services/emission_service.py`
- [Clinical assistant](https://github.com/adithya0622/delhi-model/blob/main/webapp/src/lib/clinicalEngine.ts): `webapp/src/lib/clinicalEngine.ts`
- [Backtest service](https://github.com/adithya0622/delhi-model/blob/main/backend/app/services/backtest_service.py): `backend/app/services/backtest_service.py`

### Other components

- **Operator**
- **OpenAQ**
- **NASA FIRMS**
- **Open-Meteo**

## Connections

- Operator → React console: uses
- Operator → Streamlit dashboard: uses
- React console → Forecast data hook: loads data
- Forecast data hook → Frontend API client: requests
- Frontend API client → FastAPI application: calls API
- Streamlit dashboard → FastAPI application: requests
- FastAPI application → Versioned routes: mounts router
- Versioned routes → AQI forecast integrator: serves forecast
- Versioned routes → Realtime stations: serves readings
- Versioned routes → Consensus service: collects consensus
- ML forecast routes → AQI forecast integrator: forecast basis
- Chronos routes → AQI forecast integrator: forecast context
- Backtest routes → Backtest service: runs backtest
- AQI forecast integrator → Weather providers: gets meteorology
- Weather providers → Open-Meteo: fetches weather
- AQI forecast integrator → Inversion physics: computes feedback
- AQI forecast integrator → Column model: integrates mass
- AQI forecast integrator → Plume transport: couples plume
- Plume transport → NASA FIRMS: gets detections
- Realtime stations → OpenAQ: fetches readings
- Versioned routes → Exposure service: calculates exposure
- Versioned routes → Source apportionment: calculates sources
- React console → Alert evaluation: evaluates alerts
- React console → Clinical assistant: offers guidance
- React console → Exposure service: requests exposure
- React console → Source apportionment: requests attribution