# shanu6224/vayunet architecture

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

- Interactive diagram: https://gitdiagram.com/shanu6224/vayunet
- Repository: https://github.com/shanu6224/vayunet

## Overview

VayuNet turns a device location into localized pollution-risk intelligence: satellite and weather observations inform risk scoring, possible downwind exposure, and priority verification. The PWA and Android clients present the result; Android also supports a periodic widget and push-triggered alerts. The README documents sensitive-site checks and Gemini explanations, while the sampled excerpts do not show every integration call, so those links are identified as documented or left unverified.

Main entry points: [`backend/app/services/analysis.py`](https://github.com/shanu6224/vayunet/blob/master/backend/app/services/analysis.py) (Analysis Pipeline), [`backend/app/main.py`](https://github.com/shanu6224/vayunet/blob/master/backend/app/main.py) (FastAPI), [`android/app/src/main/java/com/vayunet/app/VayuFirebaseMessagingService.kt`](https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/VayuFirebaseMessagingService.kt) (Push Handler), [`android/app/src/main/java/com/vayunet/app/MainActivity.kt`](https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/MainActivity.kt) (Android Companion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Clients"]
  node_pwa["PWA Dashboard<br/>[main.js]"]
  node_android_app["Android Companion<br/>[MainActivity.kt]"]
end

subgraph group_analysis["Risk Analysis"]
  node_api["FastAPI<br/>[main.py]"]
  node_orchestrator["Analysis Pipeline<br/>[analysis.py]"]
  node_risk["Risk &amp; Corridor<br/>[risk_engine.py]"]
  node_citizen["Citizen Evidence<br/>[citizen_service.py]"]
  node_gemini["Gemini Explanation<br/>[gemini_service.py]"]
end

subgraph group_observations["Data Sources"]
  node_gee["Sentinel-5P Data<br/>[gee_service.py]"]
  node_weather["Weather Data<br/>[weather_service.py]"]
  node_places["Sensitive Sites<br/>[places_service.py]"]
end

subgraph group_android_alerts["Android Alerts"]
  node_widget_provider["Widget Provider"]
  node_widget_worker["Widget Worker"]
  node_notifications["Notification Helper"]
  node_fcm["Push Handler"]
end

node_user(("Device User"))
node_earth_engine["Google Earth Engine"]
node_open_meteo["Open-Meteo"]
node_osm["OpenStreetMap"]
node_firebase["Firebase Cloud Messaging"]

node_user -->|"opens"| node_pwa
node_user -->|"uses"| node_android_app
node_pwa -->|"requests analysis"| node_api
node_android_app -->|"requests analysis"| node_api
node_api -->|"dispatches analysis"| node_orchestrator
node_api -->|"records reports"| node_citizen
node_orchestrator -->|"fetches satellite data"| node_gee
node_orchestrator -->|"fetches weather"| node_weather
node_orchestrator -->|"calculates risk"| node_risk
node_orchestrator -->|"checks nearby sites"| node_places
node_gee -->|"queries imagery"| node_earth_engine
node_weather -->|"fetches conditions"| node_open_meteo
node_places -->|"identifies sites"| node_osm
node_orchestrator -.->|"requests explanation"| node_gemini
node_citizen -.->|"assesses photos"| node_gemini
node_widget_provider -->|"schedules refresh"| node_widget_worker
node_widget_worker -->|"requests analysis"| node_api
node_fcm -.->|"receives push"| node_firebase
node_fcm -->|"shows alert"| node_notifications
node_fcm -->|"queues refresh"| node_widget_worker
node_notifications -->|"opens activity"| node_android_app

click node_pwa "https://github.com/shanu6224/vayunet/blob/master/frontend/src/main.js"
click node_android_app "https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/MainActivity.kt"
click node_api "https://github.com/shanu6224/vayunet/blob/master/backend/app/main.py"
click node_orchestrator "https://github.com/shanu6224/vayunet/blob/master/backend/app/services/analysis.py"
click node_risk "https://github.com/shanu6224/vayunet/blob/master/backend/app/services/risk_engine.py"
click node_citizen "https://github.com/shanu6224/vayunet/blob/master/backend/app/services/citizen_service.py"
click node_gemini "https://github.com/shanu6224/vayunet/blob/master/backend/app/services/gemini_service.py"
click node_gee "https://github.com/shanu6224/vayunet/blob/master/backend/app/services/gee_service.py"
click node_weather "https://github.com/shanu6224/vayunet/blob/master/backend/app/services/weather_service.py"
click node_places "https://github.com/shanu6224/vayunet/blob/master/backend/app/services/places_service.py"
click node_widget_provider "https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/VayuWidgetProvider.kt"
click node_widget_worker "https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/VayuWidgetWorker.kt"
click node_notifications "https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/NotificationHelper.kt"
click node_fcm "https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/VayuFirebaseMessagingService.kt"

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_pwa,node_android_app,node_user toneBlue
class node_api,node_orchestrator,node_risk,node_citizen,node_gemini toneAmber
class node_gee,node_weather,node_places toneMint
class node_widget_provider,node_widget_worker,node_notifications,node_fcm toneRose
class node_earth_engine,node_open_meteo,node_osm,node_firebase toneIndigo
```

## Components

### User Clients

- [PWA Dashboard](https://github.com/shanu6224/vayunet/blob/master/frontend/src/main.js): `frontend/src/main.js`
- [Android Companion](https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/MainActivity.kt): `android/app/src/main/java/com/vayunet/app/MainActivity.kt`

### Risk Analysis

- [FastAPI](https://github.com/shanu6224/vayunet/blob/master/backend/app/main.py): `backend/app/main.py`
- [Analysis Pipeline](https://github.com/shanu6224/vayunet/blob/master/backend/app/services/analysis.py): `backend/app/services/analysis.py`
- [Risk & Corridor](https://github.com/shanu6224/vayunet/blob/master/backend/app/services/risk_engine.py): `backend/app/services/risk_engine.py`
- [Citizen Evidence](https://github.com/shanu6224/vayunet/blob/master/backend/app/services/citizen_service.py): `backend/app/services/citizen_service.py`
- [Gemini Explanation](https://github.com/shanu6224/vayunet/blob/master/backend/app/services/gemini_service.py): `backend/app/services/gemini_service.py`

### Data Sources

- [Sentinel-5P Data](https://github.com/shanu6224/vayunet/blob/master/backend/app/services/gee_service.py): `backend/app/services/gee_service.py`
- [Weather Data](https://github.com/shanu6224/vayunet/blob/master/backend/app/services/weather_service.py): `backend/app/services/weather_service.py`
- [Sensitive Sites](https://github.com/shanu6224/vayunet/blob/master/backend/app/services/places_service.py): `backend/app/services/places_service.py`

### Android Alerts

- [Widget Provider](https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/VayuWidgetProvider.kt): `android/app/src/main/java/com/vayunet/app/VayuWidgetProvider.kt`
- [Widget Worker](https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/VayuWidgetWorker.kt): `android/app/src/main/java/com/vayunet/app/VayuWidgetWorker.kt`
- [Notification Helper](https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/NotificationHelper.kt): `android/app/src/main/java/com/vayunet/app/NotificationHelper.kt`
- [Push Handler](https://github.com/shanu6224/vayunet/blob/master/android/app/src/main/java/com/vayunet/app/VayuFirebaseMessagingService.kt): `android/app/src/main/java/com/vayunet/app/VayuFirebaseMessagingService.kt`

### Other components

- **Device User**
- **Google Earth Engine**
- **Open-Meteo**
- **OpenStreetMap**
- **Firebase Cloud Messaging**

## Connections

- Device User → PWA Dashboard: opens (evidence: `README.md`)
- Device User → Android Companion: uses (evidence: `README.md`)
- PWA Dashboard → FastAPI: requests analysis (evidence: `frontend/src/main.js`)
- Android Companion → FastAPI: requests analysis (evidence: `android/app/src/main/java/com/vayunet/app/MainActivity.kt`)
- FastAPI → Analysis Pipeline: dispatches analysis (evidence: `backend/app/main.py`)
- FastAPI → Citizen Evidence: records reports (evidence: `backend/app/main.py`)
- Analysis Pipeline → Sentinel-5P Data: fetches satellite data (evidence: `backend/app/services/analysis.py`)
- Analysis Pipeline → Weather Data: fetches weather (evidence: `backend/app/services/analysis.py`)
- Analysis Pipeline → Risk & Corridor: calculates risk (evidence: `backend/app/services/analysis.py`)
- Analysis Pipeline → Sensitive Sites: checks nearby sites (evidence: `backend/app/services/analysis.py`)
- Sentinel-5P Data → Google Earth Engine: queries imagery (evidence: `README.md`)
- Weather Data → Open-Meteo: fetches conditions (evidence: `README.md`)
- Sensitive Sites → OpenStreetMap: identifies sites (evidence: `README.md`)
- Analysis Pipeline → Gemini Explanation: requests explanation (evidence: `README.md`)
- Citizen Evidence → Gemini Explanation: assesses photos
- Widget Provider → Widget Worker: schedules refresh (evidence: `android/app/src/main/java/com/vayunet/app/VayuWidgetProvider.kt`)
- Widget Worker → FastAPI: requests analysis (evidence: `android/app/src/main/java/com/vayunet/app/VayuWidgetWorker.kt`)
- Push Handler → Firebase Cloud Messaging: receives push (evidence: `android/app/src/main/java/com/vayunet/app/VayuFirebaseMessagingService.kt`)
- Push Handler → Notification Helper: shows alert (evidence: `android/app/src/main/java/com/vayunet/app/VayuFirebaseMessagingService.kt`)
- Push Handler → Widget Worker: queues refresh (evidence: `android/app/src/main/java/com/vayunet/app/VayuFirebaseMessagingService.kt`)
- Notification Helper → Android Companion: opens activity (evidence: `android/app/src/main/java/com/vayunet/app/NotificationHelper.kt`)
