# vagbon-d/weathergpt-sih architecture

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

- Interactive diagram: https://gitdiagram.com/vagbon-d/weathergpt-sih
- Repository: https://github.com/vagbon-d/weathergpt-sih

## Overview

WeatherGPT provides multilingual weather forecasts, authoritative alerts, agricultural decision support, and conversational advisories through a web app and telephony/SMS. The principal workflow is user query and location resolution, weather and IMD knowledge retrieval, deterministic hazard/agronomic evaluation, grounded response generation, then localized text or speech. The README documents the safety pipeline and capabilities; edges backed only by that documentation are cited to the README, while source-level links use indexed references.

Main entry points: [`backend/main.py`](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/main.py) (FastAPI application), [`backend/services/grounded_advisory.py`](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/grounded_advisory.py) (Grounded advisory pipeline), [`backend/services/weather_service.py`](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/weather_service.py) (Weather aggregation), [`backend/routers/advisory.py`](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/advisory.py) (Advisory endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Interfaces"]
  node_web["Weather web app<br/>[App.jsx]"]
  node_api_client["Frontend API client<br/>[api.js]"]
  node_locale["Indic localization"]
  node_speech["Browser speech<br/>[speechManager.js]"]
end

subgraph group_api["API and Telephony"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_chat_route["Chat endpoint<br/>[chat.py]"]
  node_weather_route["Weather endpoint<br/>[weather.py]"]
  node_alert_route["Alert endpoint<br/>[alerts.py]"]
  node_advisory_route["Advisory endpoint<br/>[advisory.py]"]
  node_location_route["Location endpoint<br/>[location.py]"]
  node_language_route["Language endpoint<br/>[language.py]"]
  node_telephony["IVR and SMS<br/>[webhook.py]"]
  node_call_status["Call status feed<br/>[ws_call_status.py]"]
end

subgraph group_weather["Weather Intelligence"]
  node_weather_service["Weather aggregation<br/>[weather_service.py]"]
  node_weather_sources["Forecast providers<br/>[aggregator.py]"]
  node_weather_engine["Weather classification<br/>[weather_engine.py]"]
  node_geocoder["Photon geocoder<br/>[photon_service.py]"]
end

subgraph group_knowledge["IMD Knowledge"]
  node_imd_crawler["IMD crawler<br/>[imd_crawler.py]"]
  node_bulletin_parser["Bulletin parser<br/>[bulletin_parser.py]"]
  node_normalizer["Bulletin normalizer<br/>[normalizer.py]"]
  node_rag["Bulletin and rules retrieval<br/>[rag_service.py]"]
end

subgraph group_advisory["Grounded Advisory"]
  node_grounded["Grounded advisory pipeline"]
  node_query["Intent and temporal analysis<br/>[query_engine.py]"]
  node_agronomy["Agronomic rule evaluation"]
  node_llm["Grounded language generation<br/>[llm_service.py]"]
  node_language_service["Language processing"]
  node_bhashini["Bhashini language services"]
  node_native_tts["Native speech synthesis<br/>[native_tts.py]"]
end

node_user(("Farmer or citizen"))
node_ollama{{"Ollama LLM"}}
node_bhashini_external{{"Bhashini service"}}
node_official_imd{{"Official IMD sources"}}
node_open_meteo{{"Open-Meteo"}}
node_photon_external{{"Photon / OpenStreetMap"}}

node_user -->|"asks forecast"| node_web
node_web -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_fastapi
node_web -->|"localizes interface"| node_locale
node_locale -->|"uses speech"| node_speech
node_fastapi -->|"registers route"| node_chat_route
node_fastapi -->|"registers route"| node_weather_route
node_fastapi -->|"registers route"| node_alert_route
node_fastapi -->|"registers route"| node_advisory_route
node_fastapi -->|"registers route"| node_location_route
node_fastapi -->|"registers route"| node_language_route
node_fastapi -->|"registers webhooks"| node_telephony
node_fastapi -->|"registers feed"| node_call_status
node_weather_route -->|"fetches forecasts"| node_weather_service
node_alert_route -->|"fetches warnings"| node_weather_service
node_advisory_route -->|"fetches weather"| node_weather_service
node_advisory_route -->|"retrieves knowledge"| node_rag
node_advisory_route -->|"evaluates rules"| node_agronomy
node_location_route -->|"resolves location"| node_geocoder
node_language_route -->|"processes language"| node_language_service
node_language_route -->|"requests speech"| node_bhashini
node_language_route -->|"requests synthesis"| node_native_tts
node_weather_service -->|"resolves coordinates"| node_geocoder
node_weather_service -->|"aggregates forecasts"| node_weather_sources
node_weather_sources -->|"fetches model data"| node_open_meteo
node_weather_sources -->|"fetches IMD data"| node_official_imd
node_imd_crawler -->|"crawls bulletins"| node_official_imd
node_imd_crawler -->|"parses bulletins"| node_bulletin_parser
node_imd_crawler -->|"normalizes content"| node_normalizer
node_rag -->|"retrieves crawled data"| node_imd_crawler
node_chat_route -->|"builds grounded answer"| node_grounded
node_grounded -.->|"classifies request"| node_query
node_grounded -.->|"gets verified weather"| node_weather_service
node_grounded -.->|"retrieves evidence"| node_rag
node_grounded -.->|"evaluates hazards"| node_agronomy
node_grounded -.->|"generates response"| node_llm
node_llm -.->|"synthesizes language"| node_ollama
node_grounded -.->|"localizes response"| node_language_service
node_bhashini -.->|"calls language API"| node_bhashini_external
node_geocoder -.->|"geocodes places"| node_photon_external

click node_web "https://github.com/vagbon-d/weathergpt-sih/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/vagbon-d/weathergpt-sih/blob/main/frontend/src/api.js"
click node_locale "https://github.com/vagbon-d/weathergpt-sih/blob/main/frontend/src/i18n/LanguageContext.jsx"
click node_speech "https://github.com/vagbon-d/weathergpt-sih/blob/main/frontend/src/utils/speechManager.js"
click node_fastapi "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/main.py"
click node_chat_route "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/chat.py"
click node_weather_route "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/weather.py"
click node_alert_route "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/alerts.py"
click node_advisory_route "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/advisory.py"
click node_location_route "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/location.py"
click node_language_route "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/language.py"
click node_telephony "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/webhook.py"
click node_call_status "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/ws_call_status.py"
click node_weather_service "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/weather_service.py"
click node_weather_sources "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/weather/aggregator.py"
click node_weather_engine "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/weather_engine.py"
click node_geocoder "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/location/photon_service.py"
click node_imd_crawler "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/crawler/imd_crawler.py"
click node_bulletin_parser "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/crawler/bulletin_parser.py"
click node_normalizer "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/crawler/normalizer.py"
click node_rag "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/rag_service.py"
click node_grounded "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/grounded_advisory.py"
click node_query "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/query_engine.py"
click node_agronomy "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/advisory_service.py"
click node_llm "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/llm_service.py"
click node_language_service "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/language_service.py"
click node_bhashini "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/language/bhashini_service.py"
click node_native_tts "https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/language/native_tts.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_web,node_api_client,node_locale,node_speech toneBlue
class node_fastapi,node_chat_route,node_weather_route,node_alert_route,node_advisory_route,node_location_route,node_language_route,node_telephony,node_call_status toneAmber
class node_weather_service,node_weather_sources,node_weather_engine,node_geocoder toneMint
class node_imd_crawler,node_bulletin_parser,node_normalizer,node_rag toneRose
class node_grounded,node_query,node_agronomy,node_llm,node_language_service,node_bhashini,node_native_tts,node_user,node_ollama,node_bhashini_external,node_official_imd,node_open_meteo,node_photon_external toneIndigo
```

## Components

### User Interfaces

- [Weather web app](https://github.com/vagbon-d/weathergpt-sih/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Frontend API client](https://github.com/vagbon-d/weathergpt-sih/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Indic localization](https://github.com/vagbon-d/weathergpt-sih/blob/main/frontend/src/i18n/LanguageContext.jsx): `frontend/src/i18n/LanguageContext.jsx`
- [Browser speech](https://github.com/vagbon-d/weathergpt-sih/blob/main/frontend/src/utils/speechManager.js): `frontend/src/utils/speechManager.js`

### API and Telephony

- [FastAPI application](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/main.py): `backend/main.py`
- [Chat endpoint](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/chat.py): `backend/routers/chat.py`
- [Weather endpoint](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/weather.py): `backend/routers/weather.py`
- [Alert endpoint](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/alerts.py): `backend/routers/alerts.py`
- [Advisory endpoint](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/advisory.py): `backend/routers/advisory.py`
- [Location endpoint](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/location.py): `backend/routers/location.py`
- [Language endpoint](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/language.py): `backend/routers/language.py`
- [IVR and SMS](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/webhook.py): `backend/routers/webhook.py`
- [Call status feed](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/routers/ws_call_status.py): `backend/routers/ws_call_status.py`

### Weather Intelligence

- [Weather aggregation](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/weather_service.py): `backend/services/weather_service.py`
- [Forecast providers](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/weather/aggregator.py): `backend/services/weather/aggregator.py`
- [Weather classification](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/weather_engine.py): `backend/weather_engine.py`
- [Photon geocoder](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/location/photon_service.py): `backend/services/location/photon_service.py`

### IMD Knowledge

- [IMD crawler](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/crawler/imd_crawler.py): `backend/services/crawler/imd_crawler.py`
- [Bulletin parser](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/crawler/bulletin_parser.py): `backend/services/crawler/bulletin_parser.py`
- [Bulletin normalizer](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/crawler/normalizer.py): `backend/services/crawler/normalizer.py`
- [Bulletin and rules retrieval](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/rag_service.py): `backend/services/rag_service.py`

### Grounded Advisory

- [Grounded advisory pipeline](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/grounded_advisory.py): `backend/services/grounded_advisory.py`
- [Intent and temporal analysis](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/query_engine.py): `backend/services/query_engine.py`
- [Agronomic rule evaluation](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/advisory_service.py): `backend/services/advisory_service.py`
- [Grounded language generation](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/llm_service.py): `backend/services/llm_service.py`
- [Language processing](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/language_service.py): `backend/services/language_service.py`
- [Bhashini language services](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/language/bhashini_service.py): `backend/services/language/bhashini_service.py`
- [Native speech synthesis](https://github.com/vagbon-d/weathergpt-sih/blob/main/backend/services/language/native_tts.py): `backend/services/language/native_tts.py`

### Other components

- **Farmer or citizen**
- **Ollama LLM**
- **Bhashini service**
- **Official IMD sources**
- **Open-Meteo**
- **Photon / OpenStreetMap**

## Connections

- Farmer or citizen → Weather web app: asks forecast (evidence: `README.md`)
- Weather web app → Frontend API client: requests data (evidence: `frontend/src/App.jsx`)
- Frontend API client → FastAPI application: calls API (evidence: `README.md`)
- Weather web app → Indic localization: localizes interface (evidence: `frontend/src/App.jsx`)
- Indic localization → Browser speech: uses speech (evidence: `frontend/src/i18n/LanguageContext.jsx`)
- FastAPI application → Chat endpoint: registers route (evidence: `backend/main.py`)
- FastAPI application → Weather endpoint: registers route (evidence: `backend/main.py`)
- FastAPI application → Alert endpoint: registers route (evidence: `backend/main.py`)
- FastAPI application → Advisory endpoint: registers route (evidence: `backend/main.py`)
- FastAPI application → Location endpoint: registers route (evidence: `backend/main.py`)
- FastAPI application → Language endpoint: registers route (evidence: `backend/main.py`)
- FastAPI application → IVR and SMS: registers webhooks (evidence: `backend/main.py`)
- FastAPI application → Call status feed: registers feed (evidence: `backend/main.py`)
- Weather endpoint → Weather aggregation: fetches forecasts (evidence: `backend/routers/weather.py`)
- Alert endpoint → Weather aggregation: fetches warnings (evidence: `backend/routers/alerts.py`)
- Advisory endpoint → Weather aggregation: fetches weather (evidence: `backend/routers/advisory.py`)
- Advisory endpoint → Bulletin and rules retrieval: retrieves knowledge (evidence: `backend/routers/advisory.py`)
- Advisory endpoint → Agronomic rule evaluation: evaluates rules (evidence: `backend/routers/advisory.py`)
- Location endpoint → Photon geocoder: resolves location (evidence: `backend/routers/location.py`)
- Language endpoint → Language processing: processes language (evidence: `backend/routers/language.py`)
- Language endpoint → Bhashini language services: requests speech (evidence: `backend/routers/language.py`)
- Language endpoint → Native speech synthesis: requests synthesis (evidence: `backend/routers/language.py`)
- Weather aggregation → Photon geocoder: resolves coordinates (evidence: `backend/services/weather_service.py`)
- Weather aggregation → Forecast providers: aggregates forecasts (evidence: `backend/services/weather_service.py`)
- Forecast providers → Open-Meteo: fetches model data (evidence: `README.md`)
- Forecast providers → Official IMD sources: fetches IMD data (evidence: `README.md`)
- IMD crawler → Official IMD sources: crawls bulletins (evidence: `README.md`)
- IMD crawler → Bulletin parser: parses bulletins (evidence: `backend/services/crawler/imd_crawler.py`)
- IMD crawler → Bulletin normalizer: normalizes content (evidence: `backend/services/crawler/imd_crawler.py`)
- Bulletin and rules retrieval → IMD crawler: retrieves crawled data (evidence: `backend/services/rag_service.py`)
- Chat endpoint → Grounded advisory pipeline: builds grounded answer (evidence: `backend/routers/chat.py`)
- Grounded advisory pipeline → Intent and temporal analysis: classifies request (evidence: `README.md`)
- Grounded advisory pipeline → Weather aggregation: gets verified weather (evidence: `README.md`)
- Grounded advisory pipeline → Bulletin and rules retrieval: retrieves evidence (evidence: `README.md`)
- Grounded advisory pipeline → Agronomic rule evaluation: evaluates hazards (evidence: `README.md`)
- Grounded advisory pipeline → Grounded language generation: generates response (evidence: `README.md`)
- Grounded language generation → Ollama LLM: synthesizes language (evidence: `README.md`)
- Grounded advisory pipeline → Language processing: localizes response (evidence: `README.md`)
- Bhashini language services → Bhashini service: calls language API (evidence: `backend/services/language/bhashini_service.py`)
- Photon geocoder → Photon / OpenStreetMap: geocodes places (evidence: `backend/services/location/photon_service.py`)
