# ashrithakadarla/airmind-ai architecture

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

- Interactive diagram: https://gitdiagram.com/ashrithakadarla/airmind-ai
- Repository: https://github.com/ashrithakadarla/airmind-ai

## Overview

AirMind AI is a city-focused air-quality intelligence platform. A user selects a city in the React dashboard, which requests current conditions and history from the backend; prediction capabilities extend this workflow with current and 24-/72-hour forecasts and health guidance. The backend collects environmental data, stores snapshots, and exposes API routers, while the frontend presents maps and historical/pollutant analytics. README-described capabilities are included, but links into unsampled API routes and collector internals are omitted where exact wiring cannot be confirmed.

Main entry points: [`frontend/src/pages/Home.jsx`](https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/pages/Home.jsx) (Live dashboard), [`backend/app/main.py`](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/main.py) (FastAPI app), [`frontend/src/router.jsx`](https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/router.jsx) (Page router), [`backend/app/integrations/data_collector.py`](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/integrations/data_collector.py) (Data collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["React Dashboard"]
  node_app["React app<br/>[App.jsx]"]
  node_router["Page router<br/>[router.jsx]"]
  node_city["Selected city<br/>[CityContext.jsx]"]
  node_home["Live dashboard<br/>[Home.jsx]"]
  node_prediction_page["Forecast page<br/>[Prediction.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_visuals["Maps and charts<br/>[AQIMap.jsx]"]
  node_health["Health guidance"]
end

subgraph group_backend["Backend API"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_aqi_api["AQI endpoints<br/>[aqi.py]"]
  node_environment_api["Environment endpoints<br/>[environment.py]"]
  node_prediction_api["Prediction endpoints<br/>[prediction.py]"]
  node_aqi_service["AQI service<br/>[aqi_service.py]"]
  node_environment_service["Environment service"]
  node_repository["AQI repository<br/>[aqi_repository.py]"]
  node_mongo[("MongoDB<br/>[mongodb.py]")]
end

subgraph group_environment["Environmental Data"]
  node_collector["Data collector<br/>[data_collector.py]"]
  node_geocoding["City geocoding<br/>[geocoding.py]"]
  node_weather["Weather integration<br/>[weather_service.py]"]
  node_openweather_aqi["OpenWeather AQI<br/>[openweather_aqi.py]"]
end

subgraph group_intelligence["Prediction Intelligence"]
  node_prediction_service["Prediction service"]
  node_predictor["AQI predictor<br/>[predictor.py]"]
  node_model["Prediction models<br/>[predict.py]"]
end

node_citizen(("City user"))
node_openweather["OpenWeather APIs"]

node_citizen -->|"uses"| node_app
node_app -->|"renders"| node_router
node_router -->|"routes"| node_home
node_router -->|"routes"| node_prediction_page
node_home -->|"reads city"| node_city
node_home -->|"requests data"| node_api_client
node_api_client -->|"sends requests"| node_fastapi
node_home -->|"renders analytics"| node_visuals
node_fastapi -->|"registers routes"| node_aqi_api
node_fastapi -->|"registers routes"| node_environment_api
node_fastapi -->|"registers routes"| node_prediction_api
node_aqi_service -->|"collects data"| node_collector
node_aqi_service -->|"stores and reads"| node_repository
node_repository -->|"queries and writes"| node_mongo
node_environment_service -->|"reads environment"| node_repository
node_weather -->|"gets coordinates"| node_geocoding
node_collector -->|"collects AQI"| node_openweather_aqi
node_collector -->|"collects weather"| node_weather
node_openweather_aqi -->|"fetches air data"| node_openweather
node_weather -->|"fetches weather"| node_openweather
node_geocoding -->|"geocodes city"| node_openweather
node_prediction_service -->|"refreshes data"| node_aqi_service
node_prediction_service -->|"requests predictions"| node_predictor
node_predictor -->|"uses models"| node_model
node_prediction_page -.->|"uses guidance"| node_health

click node_app "https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/App.jsx"
click node_router "https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/router.jsx"
click node_city "https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/context/CityContext.jsx"
click node_home "https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/pages/Home.jsx"
click node_prediction_page "https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/pages/Prediction.jsx"
click node_api_client "https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/services/api.js"
click node_visuals "https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/components/Map/AQIMap.jsx"
click node_health "https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/utils/healthRecommendations.js"
click node_fastapi "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/main.py"
click node_aqi_api "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/api/aqi.py"
click node_environment_api "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/api/environment.py"
click node_prediction_api "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/api/prediction.py"
click node_aqi_service "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/services/aqi_service.py"
click node_environment_service "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/services/environment_service.py"
click node_repository "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/repositories/aqi_repository.py"
click node_mongo "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/database/mongodb.py"
click node_collector "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/integrations/data_collector.py"
click node_geocoding "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/integrations/geocoding.py"
click node_weather "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/integrations/weather_service.py"
click node_openweather_aqi "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/integrations/openweather_aqi.py"
click node_prediction_service "https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/services/prediction_service.py"
click node_predictor "https://github.com/ashrithakadarla/airmind-ai/blob/main/ml/predictor.py"
click node_model "https://github.com/ashrithakadarla/airmind-ai/blob/main/ml/predict.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_router,node_city,node_home,node_prediction_page,node_api_client,node_visuals,node_health,node_citizen toneBlue
class node_fastapi,node_aqi_api,node_environment_api,node_prediction_api,node_aqi_service,node_environment_service,node_repository,node_mongo toneAmber
class node_collector,node_geocoding,node_weather,node_openweather_aqi,node_openweather toneMint
class node_prediction_service,node_predictor,node_model toneRose
```

## Components

### React Dashboard

- [React app](https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Page router](https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/router.jsx): `frontend/src/router.jsx`
- [Selected city](https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/context/CityContext.jsx): `frontend/src/context/CityContext.jsx`
- [Live dashboard](https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/pages/Home.jsx): `frontend/src/pages/Home.jsx`
- [Forecast page](https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/pages/Prediction.jsx): `frontend/src/pages/Prediction.jsx`
- [API client](https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Maps and charts](https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/components/Map/AQIMap.jsx): `frontend/src/components/Map/AQIMap.jsx`
- [Health guidance](https://github.com/ashrithakadarla/airmind-ai/blob/main/frontend/src/utils/healthRecommendations.js): `frontend/src/utils/healthRecommendations.js`

### Backend API

- [FastAPI app](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [AQI endpoints](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/api/aqi.py): `backend/app/api/aqi.py`
- [Environment endpoints](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/api/environment.py): `backend/app/api/environment.py`
- [Prediction endpoints](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/api/prediction.py): `backend/app/api/prediction.py`
- [AQI service](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/services/aqi_service.py): `backend/app/services/aqi_service.py`
- [Environment service](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/services/environment_service.py): `backend/app/services/environment_service.py`
- [AQI repository](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/repositories/aqi_repository.py): `backend/app/repositories/aqi_repository.py`
- [MongoDB](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/database/mongodb.py): `backend/app/database/mongodb.py`

### Environmental Data

- [Data collector](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/integrations/data_collector.py): `backend/app/integrations/data_collector.py`
- [City geocoding](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/integrations/geocoding.py): `backend/app/integrations/geocoding.py`
- [Weather integration](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/integrations/weather_service.py): `backend/app/integrations/weather_service.py`
- [OpenWeather AQI](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/integrations/openweather_aqi.py): `backend/app/integrations/openweather_aqi.py`

### Prediction Intelligence

- [Prediction service](https://github.com/ashrithakadarla/airmind-ai/blob/main/backend/app/services/prediction_service.py): `backend/app/services/prediction_service.py`
- [AQI predictor](https://github.com/ashrithakadarla/airmind-ai/blob/main/ml/predictor.py): `ml/predictor.py`
- [Prediction models](https://github.com/ashrithakadarla/airmind-ai/blob/main/ml/predict.py): `ml/predict.py`

### Other components

- **City user**
- **OpenWeather APIs**

## Connections

- City user → React app: uses
- React app → Page router: renders
- Page router → Live dashboard: routes
- Page router → Forecast page: routes
- Live dashboard → Selected city: reads city
- Live dashboard → API client: requests data
- API client → FastAPI app: sends requests
- Live dashboard → Maps and charts: renders analytics
- FastAPI app → AQI endpoints: registers routes
- FastAPI app → Environment endpoints: registers routes
- FastAPI app → Prediction endpoints: registers routes
- AQI service → Data collector: collects data
- AQI service → AQI repository: stores and reads
- AQI repository → MongoDB: queries and writes
- Environment service → AQI repository: reads environment
- Weather integration → City geocoding: gets coordinates
- Data collector → OpenWeather AQI: collects AQI
- Data collector → Weather integration: collects weather
- OpenWeather AQI → OpenWeather APIs: fetches air data
- Weather integration → OpenWeather APIs: fetches weather
- City geocoding → OpenWeather APIs: geocodes city
- Prediction service → AQI service: refreshes data
- Prediction service → AQI predictor: requests predictions
- AQI predictor → Prediction models: uses models
- Forecast page → Health guidance: uses guidance