# sumedha-t/urban-air-quality-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/sumedha-t/urban-air-quality-intelligence
- Repository: https://github.com/sumedha-t/urban-air-quality-intelligence

## Overview

The platform presents air-quality intelligence through administrator and citizen portals, while its backend collects AQI, weather, and traffic data, fuses snapshots, and exposes collection and history routes. The UI also offers forecast, attribution, intervention-priority, climate, health, and citizen-report experiences; the README describes several AI capabilities as planned, and the frontend API currently selects mock data. Edges reflect shown calls, imports listed in the SOURCE INDEX, or README claims; unsampled UI internals and planned backend agents are not asserted as implemented.

Main entry points: [`backend/data_collectors`](https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/backend/data_collectors) (Source collectors), [`frontend/src/App.jsx`](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/App.jsx) (Role router), [`backend/routes`](https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/backend/routes) (API routes), [`backend/agents/data_fusion.py`](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/agents/data_fusion.py) (Data fusion agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["User portals"]
  node_app["Role router<br/>[App.jsx]"]
  node_layout["Portal layout<br/>[MainLayout.jsx]"]
  node_admin["Admin workspace"]
  node_citizen["Citizen workspace"]
  node_map["Interactive map<br/>[InteractiveMap.jsx]"]
  node_forecast["Forecast views<br/>[Forecast.jsx]"]
  node_priority["Priority planning"]
  node_climate["Climate analysis"]
  node_health["Health assistant"]
  node_report["Citizen reports<br/>[ReportPage.jsx]"]
  node_api_client["Frontend data service<br/>[api.js]"]
  node_mock["Mock intelligence data<br/>[mockData.js]"]
end

subgraph group_backend["API and collection"]
  node_entry["FastAPI entry<br/>[main.py]"]
  node_routes["API routes"]
  node_fusion["Data fusion agent<br/>[data_fusion.py]"]
  node_scheduler["Collection scheduler<br/>[scheduler.py]"]
  node_collectors["Source collectors"]
  node_http["HTTP client<br/>[http_client.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_storage["Persistence"]
  node_repositories["Data repositories"]
  node_mongo[("MongoDB manager<br/>[mongodb.py]")]
end

subgraph group_integrations["External sources"]
  node_weather_api{{"OpenWeather APIs"}}
  node_tomtom{{"TomTom Traffic API"}}
end

node_user(("Portal user"))

node_user -->|"uses"| node_app
node_app -->|"loads locations"| node_api_client
node_app -->|"renders"| node_layout
node_app -->|"routes admin"| node_admin
node_app -->|"routes citizen"| node_citizen
node_admin -->|"requests data"| node_api_client
node_citizen -->|"requests data"| node_api_client
node_admin -->|"renders map"| node_map
node_api_client -->|"uses mock data"| node_mock
node_entry -->|"registers routes"| node_routes
node_entry -->|"connects lifecycle"| node_mongo
node_entry -->|"starts scheduler"| node_scheduler
node_scheduler -->|"invokes fusion"| node_fusion
node_fusion -->|"collects sources"| node_collectors
node_fusion -->|"saves snapshot"| node_repositories
node_collectors -->|"fetches JSON"| node_http
node_collectors -->|"saves readings"| node_repositories
node_collectors -->|"reads credentials"| node_settings
node_collectors -->|"queries weather"| node_weather_api
node_collectors -->|"queries traffic"| node_tomtom
node_repositories -->|"uses database"| node_mongo
node_routes -->|"serves source calls"| node_collectors
node_routes -->|"serves fusion call"| node_fusion
node_routes -->|"reads history"| node_repositories

click node_app "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/App.jsx"
click node_layout "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/components/Layout/MainLayout.jsx"
click node_admin "https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/frontend/src/pages/Admin"
click node_citizen "https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/frontend/src/pages/Citizen"
click node_map "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/components/Map/InteractiveMap.jsx"
click node_forecast "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/pages/Admin/Forecast.jsx"
click node_priority "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/pages/Admin/PriorityDashboard.jsx"
click node_climate "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/pages/Citizen/ClimateAnalysis.jsx"
click node_health "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/pages/Citizen/HealthAssistant.jsx"
click node_report "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/pages/Citizen/ReportPage.jsx"
click node_api_client "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/services/api.js"
click node_mock "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/services/mockData.js"
click node_entry "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/main.py"
click node_routes "https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/backend/routes"
click node_fusion "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/agents/data_fusion.py"
click node_scheduler "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/scheduler/scheduler.py"
click node_collectors "https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/backend/data_collectors"
click node_http "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/utils/http_client.py"
click node_settings "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/config/settings.py"
click node_repositories "https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/backend/repositories"
click node_mongo "https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/database/mongodb.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_app,node_layout,node_admin,node_citizen,node_map,node_forecast,node_priority,node_climate,node_health,node_report,node_api_client,node_mock,node_user toneBlue
class node_entry,node_routes,node_fusion,node_scheduler,node_collectors,node_http,node_settings toneAmber
class node_repositories,node_mongo toneMint
class node_weather_api,node_tomtom toneRose
```

## Components

### User portals

- [Role router](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Portal layout](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/components/Layout/MainLayout.jsx): `frontend/src/components/Layout/MainLayout.jsx`
- [Admin workspace](https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/frontend/src/pages/Admin): `frontend/src/pages/Admin`
- [Citizen workspace](https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/frontend/src/pages/Citizen): `frontend/src/pages/Citizen`
- [Interactive map](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/components/Map/InteractiveMap.jsx): `frontend/src/components/Map/InteractiveMap.jsx`
- [Forecast views](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/pages/Admin/Forecast.jsx): `frontend/src/pages/Admin/Forecast.jsx`
- [Priority planning](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/pages/Admin/PriorityDashboard.jsx): `frontend/src/pages/Admin/PriorityDashboard.jsx`
- [Climate analysis](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/pages/Citizen/ClimateAnalysis.jsx): `frontend/src/pages/Citizen/ClimateAnalysis.jsx`
- [Health assistant](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/pages/Citizen/HealthAssistant.jsx): `frontend/src/pages/Citizen/HealthAssistant.jsx`
- [Citizen reports](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/pages/Citizen/ReportPage.jsx): `frontend/src/pages/Citizen/ReportPage.jsx`
- [Frontend data service](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Mock intelligence data](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/frontend/src/services/mockData.js): `frontend/src/services/mockData.js`

### API and collection

- [FastAPI entry](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/main.py): `backend/main.py`
- [API routes](https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/backend/routes): `backend/routes`
- [Data fusion agent](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/agents/data_fusion.py): `backend/agents/data_fusion.py`
- [Collection scheduler](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/scheduler/scheduler.py): `backend/scheduler/scheduler.py`
- [Source collectors](https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/backend/data_collectors): `backend/data_collectors`
- [HTTP client](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/utils/http_client.py): `backend/utils/http_client.py`
- [Runtime settings](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/config/settings.py): `backend/config/settings.py`

### Persistence

- [Data repositories](https://github.com/sumedha-t/urban-air-quality-intelligence/tree/main/backend/repositories): `backend/repositories`
- [MongoDB manager](https://github.com/sumedha-t/urban-air-quality-intelligence/blob/main/backend/database/mongodb.py): `backend/database/mongodb.py`

### External sources

- **OpenWeather APIs**
- **TomTom Traffic API**

### Other components

- **Portal user**

## Connections

- Portal user → Role router: uses
- Role router → Frontend data service: loads locations (evidence: `frontend/src/App.jsx`)
- Role router → Portal layout: renders (evidence: `frontend/src/App.jsx`)
- Role router → Admin workspace: routes admin (evidence: `frontend/src/App.jsx`)
- Role router → Citizen workspace: routes citizen (evidence: `frontend/src/App.jsx`)
- Admin workspace → Frontend data service: requests data (evidence: `frontend/src/pages/Admin/Forecast.jsx`)
- Citizen workspace → Frontend data service: requests data (evidence: `frontend/src/pages/Citizen/ClimateAnalysis.jsx`)
- Admin workspace → Interactive map: renders map (evidence: `frontend/src/pages/Admin/MapGIS.jsx`)
- Frontend data service → Mock intelligence data: uses mock data (evidence: `frontend/src/services/api.js`)
- FastAPI entry → API routes: registers routes (evidence: `backend/main.py`)
- FastAPI entry → MongoDB manager: connects lifecycle (evidence: `backend/main.py`)
- FastAPI entry → Collection scheduler: starts scheduler (evidence: `backend/main.py`)
- Collection scheduler → Data fusion agent: invokes fusion (evidence: `backend/scheduler/scheduler.py`)
- Data fusion agent → Source collectors: collects sources (evidence: `backend/agents/data_fusion.py`)
- Data fusion agent → Data repositories: saves snapshot (evidence: `backend/agents/data_fusion.py`)
- Source collectors → HTTP client: fetches JSON (evidence: `backend/data_collectors/weather.py`)
- Source collectors → Data repositories: saves readings (evidence: `backend/data_collectors/weather.py`)
- Source collectors → Runtime settings: reads credentials (evidence: `backend/data_collectors/weather.py`)
- Source collectors → OpenWeather APIs: queries weather (evidence: `backend/data_collectors/weather.py`)
- Source collectors → TomTom Traffic API: queries traffic (evidence: `backend/data_collectors/traffic.py`)
- Data repositories → MongoDB manager: uses database (evidence: `backend/repositories/base_repository.py`)
- API routes → Source collectors: serves source calls (evidence: `backend/routes/aqi.py`)
- API routes → Data fusion agent: serves fusion call (evidence: `backend/routes/fusion.py`)
- API routes → Data repositories: reads history (evidence: `backend/routes/history.py`)
