# ahvaan-india/ahvaan architecture

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

- Interactive diagram: https://gitdiagram.com/ahvaan-india/ahvaan
- Repository: https://github.com/ahvaan-india/ahvaan

## Overview

Ahvaan is a ward-level urban heat resilience and municipal decision-support platform. Operators explore citywide heat exposure, inspect ward telemetry and forecasts, compare index accuracy, and dispatch heat advisories; a stateless assistant answers questions using ward context. The sampled routes establish the risk, board, forecast, analysis, accuracy, and chat service flows. Several UI and subsystem links are based on the README and route structure; unsampled implementations are represented only where their paths are supported.

Main entry points: [`lib/db/queries.ts`](https://github.com/ahvaan-india/ahvaan/blob/main/lib/db/queries.ts) (Database queries), [`app/maps/page.tsx`](https://github.com/ahvaan-india/ahvaan/blob/main/app/maps/page.tsx) (Ward heat map), [`app/api/forecast/[locationId]/route.ts`](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/forecast/%5BlocationId%5D/route.ts) (Forecast API), [`app/alerts/page.tsx`](https://github.com/ahvaan-india/ahvaan/blob/main/app/alerts/page.tsx) (Alert center)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Operator Experience"]
  node_maps["Ward heat map<br/>[page.tsx]"]
  node_mapview["Kolkata map<br/>[KolkataMap.tsx]"]
  node_analysisui["Ward analysis<br/>[page.tsx]"]
  node_overview["Metro overview<br/>[page.tsx]"]
  node_alertsui["Alert center<br/>[page.tsx]"]
  node_chatwidget["AI assistant<br/>[ChatbotWidget.tsx]"]
end

subgraph group_api["Application Services"]
  node_heatmapapi["Heat map API<br/>[route.ts]"]
  node_wardsapi["Ward catalogue API<br/>[route.ts]"]
  node_telemetryapi["Telemetry API<br/>[route.ts]"]
  node_summaryapi["City summary API<br/>[route.ts]"]
  node_riskapi["Risk API<br/>[route.ts]"]
  node_forecastapi["Forecast API<br/>[route.ts]"]
  node_analysisapi["Analysis API<br/>[route.ts]"]
  node_accuracyapi["Accuracy API<br/>[route.ts]"]
  node_chatapi["Chat API<br/>[route.ts]"]
  node_emailapi["Email dispatch API<br/>[route.ts]"]
end

subgraph group_science["Heat Risk Science"]
  node_board["City board<br/>[board.ts]"]
  node_riskengine["HeatShield engine<br/>[service.ts]"]
  node_forecastengine["Forecast model<br/>[forecast.ts]"]
  node_analysislogic["Analysis summaries<br/>[analysis.ts]"]
  node_accuracy["Index comparison<br/>[accuracy.ts]"]
  node_alertlogic["Alert evaluation<br/>[alerts.ts]"]
  node_context["Ward chat context<br/>[context.ts]"]
end

subgraph group_data["Data and Integrations"]
  node_chatprovider["Cloudflare AI<br/>[cloudflare.ts]"]
  node_emailservice["Email sender<br/>[send.ts]"]
  node_queries["Database queries<br/>[queries.ts]"]
  node_postgres[("Postgres")]
  node_redis[("Redis cache<br/>[redis.ts]")]
  node_references["Reference weather APIs"]
end

node_operator(("Municipal operator"))

node_operator -->|"opens map"| node_maps
node_operator -->|"selects ward"| node_analysisui
node_operator -->|"checks city"| node_overview
node_operator -->|"reviews alerts"| node_alertsui
node_maps -->|"renders wards"| node_mapview
node_maps -->|"loads heat map"| node_heatmapapi
node_maps -->|"loads catalogue"| node_wardsapi
node_maps -->|"loads telemetry"| node_telemetryapi
node_overview -->|"loads KPIs"| node_summaryapi
node_analysisui -->|"loads analysis"| node_analysisapi
node_analysisui -->|"loads forecast"| node_forecastapi
node_alertsui -->|"reads risk"| node_riskapi
node_alertsui -->|"evaluates triggers"| node_alertlogic
node_alertsui -->|"dispatches advisory"| node_emailapi
node_chatwidget -->|"sends question"| node_chatapi
node_heatmapapi -->|"requests board"| node_board
node_summaryapi -->|"requests board"| node_board
node_board -->|"reads weather and census"| node_queries
node_board -->|"computes ward risk"| node_riskengine
node_heatmapapi -->|"loads ward geometry"| node_queries
node_heatmapapi -->|"caches payload"| node_redis
node_summaryapi -->|"caches summary"| node_redis
node_wardsapi -->|"loads wards"| node_queries
node_telemetryapi -->|"reads ward data"| node_queries
node_telemetryapi -->|"computes risk"| node_riskengine
node_riskapi -->|"reads inputs"| node_queries
node_riskapi -->|"builds risk response"| node_riskengine
node_forecastapi -->|"reads inputs"| node_queries
node_forecastapi -->|"computes outlook"| node_forecastengine
node_forecastapi -->|"summarizes analysis"| node_analysislogic
node_forecastapi -->|"caches response"| node_redis
node_analysisapi -->|"reads analysis rows"| node_queries
node_analysisapi -->|"summarizes days"| node_analysislogic
node_accuracyapi -->|"compares indices"| node_accuracy
node_accuracy -.->|"requests benchmarks"| node_references
node_chatapi -->|"builds ward context"| node_context
node_chatapi -->|"sends prompt"| node_chatprovider
node_context -->|"reads telemetry"| node_queries
node_emailapi -->|"sends email"| node_emailservice
node_queries -->|"reads records"| node_postgres
node_redis -.->|"falls back to queries"| node_postgres

click node_maps "https://github.com/ahvaan-india/ahvaan/blob/main/app/maps/page.tsx"
click node_mapview "https://github.com/ahvaan-india/ahvaan/blob/main/components/map/KolkataMap.tsx"
click node_analysisui "https://github.com/ahvaan-india/ahvaan/blob/main/app/analysis/page.tsx"
click node_overview "https://github.com/ahvaan-india/ahvaan/blob/main/app/overview/page.tsx"
click node_alertsui "https://github.com/ahvaan-india/ahvaan/blob/main/app/alerts/page.tsx"
click node_chatwidget "https://github.com/ahvaan-india/ahvaan/blob/main/components/ChatbotWidget.tsx"
click node_heatmapapi "https://github.com/ahvaan-india/ahvaan/blob/main/app/api/wards/heatmap/route.ts"
click node_wardsapi "https://github.com/ahvaan-india/ahvaan/blob/main/app/api/wards/route.ts"
click node_telemetryapi "https://github.com/ahvaan-india/ahvaan/blob/main/app/api/wards/%5BwardId%5D/telemetry/route.ts"
click node_summaryapi "https://github.com/ahvaan-india/ahvaan/blob/main/app/api/wards/summary/route.ts"
click node_riskapi "https://github.com/ahvaan-india/ahvaan/blob/main/app/api/risk/route.ts"
click node_forecastapi "https://github.com/ahvaan-india/ahvaan/blob/main/app/api/forecast/%5BlocationId%5D/route.ts"
click node_analysisapi "https://github.com/ahvaan-india/ahvaan/blob/main/app/api/analysis/route.ts"
click node_accuracyapi "https://github.com/ahvaan-india/ahvaan/blob/main/app/api/accuracy/route.ts"
click node_chatapi "https://github.com/ahvaan-india/ahvaan/blob/main/app/api/chat/route.ts"
click node_emailapi "https://github.com/ahvaan-india/ahvaan/blob/main/app/api/email/send/route.ts"
click node_board "https://github.com/ahvaan-india/ahvaan/blob/main/lib/board.ts"
click node_riskengine "https://github.com/ahvaan-india/ahvaan/blob/main/lib/heatshield/service.ts"
click node_forecastengine "https://github.com/ahvaan-india/ahvaan/blob/main/lib/heatshield/forecast.ts"
click node_analysislogic "https://github.com/ahvaan-india/ahvaan/blob/main/lib/analysis.ts"
click node_accuracy "https://github.com/ahvaan-india/ahvaan/blob/main/lib/accuracy.ts"
click node_alertlogic "https://github.com/ahvaan-india/ahvaan/blob/main/lib/alerts.ts"
click node_context "https://github.com/ahvaan-india/ahvaan/blob/main/lib/chatbot/context.ts"
click node_chatprovider "https://github.com/ahvaan-india/ahvaan/blob/main/lib/chatbot/cloudflare.ts"
click node_emailservice "https://github.com/ahvaan-india/ahvaan/blob/main/lib/email/send.ts"
click node_queries "https://github.com/ahvaan-india/ahvaan/blob/main/lib/db/queries.ts"
click node_redis "https://github.com/ahvaan-india/ahvaan/blob/main/lib/redis.ts"

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_maps,node_mapview,node_analysisui,node_overview,node_alertsui,node_chatwidget toneBlue
class node_heatmapapi,node_wardsapi,node_telemetryapi,node_summaryapi,node_riskapi,node_forecastapi,node_analysisapi,node_accuracyapi,node_chatapi,node_emailapi toneAmber
class node_board,node_riskengine,node_forecastengine,node_analysislogic,node_accuracy,node_alertlogic,node_context toneMint
class node_chatprovider,node_emailservice,node_queries,node_postgres,node_redis,node_references toneRose
class node_operator toneIndigo
```

## Components

### Operator Experience

- [Ward heat map](https://github.com/ahvaan-india/ahvaan/blob/main/app/maps/page.tsx): `app/maps/page.tsx`
- [Kolkata map](https://github.com/ahvaan-india/ahvaan/blob/main/components/map/KolkataMap.tsx): `components/map/KolkataMap.tsx`
- [Ward analysis](https://github.com/ahvaan-india/ahvaan/blob/main/app/analysis/page.tsx): `app/analysis/page.tsx`
- [Metro overview](https://github.com/ahvaan-india/ahvaan/blob/main/app/overview/page.tsx): `app/overview/page.tsx`
- [Alert center](https://github.com/ahvaan-india/ahvaan/blob/main/app/alerts/page.tsx): `app/alerts/page.tsx`
- [AI assistant](https://github.com/ahvaan-india/ahvaan/blob/main/components/ChatbotWidget.tsx): `components/ChatbotWidget.tsx`

### Application Services

- [Heat map API](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/wards/heatmap/route.ts): `app/api/wards/heatmap/route.ts`
- [Ward catalogue API](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/wards/route.ts): `app/api/wards/route.ts`
- [Telemetry API](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/wards/%5BwardId%5D/telemetry/route.ts): `app/api/wards/[wardId]/telemetry/route.ts`
- [City summary API](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/wards/summary/route.ts): `app/api/wards/summary/route.ts`
- [Risk API](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/risk/route.ts): `app/api/risk/route.ts`
- [Forecast API](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/forecast/%5BlocationId%5D/route.ts): `app/api/forecast/[locationId]/route.ts`
- [Analysis API](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/analysis/route.ts): `app/api/analysis/route.ts`
- [Accuracy API](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/accuracy/route.ts): `app/api/accuracy/route.ts`
- [Chat API](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/chat/route.ts): `app/api/chat/route.ts`
- [Email dispatch API](https://github.com/ahvaan-india/ahvaan/blob/main/app/api/email/send/route.ts): `app/api/email/send/route.ts`

### Heat Risk Science

- [City board](https://github.com/ahvaan-india/ahvaan/blob/main/lib/board.ts): `lib/board.ts`
- [HeatShield engine](https://github.com/ahvaan-india/ahvaan/blob/main/lib/heatshield/service.ts): `lib/heatshield/service.ts`
- [Forecast model](https://github.com/ahvaan-india/ahvaan/blob/main/lib/heatshield/forecast.ts): `lib/heatshield/forecast.ts`
- [Analysis summaries](https://github.com/ahvaan-india/ahvaan/blob/main/lib/analysis.ts): `lib/analysis.ts`
- [Index comparison](https://github.com/ahvaan-india/ahvaan/blob/main/lib/accuracy.ts): `lib/accuracy.ts`
- [Alert evaluation](https://github.com/ahvaan-india/ahvaan/blob/main/lib/alerts.ts): `lib/alerts.ts`
- [Ward chat context](https://github.com/ahvaan-india/ahvaan/blob/main/lib/chatbot/context.ts): `lib/chatbot/context.ts`

### Data and Integrations

- [Cloudflare AI](https://github.com/ahvaan-india/ahvaan/blob/main/lib/chatbot/cloudflare.ts): `lib/chatbot/cloudflare.ts`
- [Email sender](https://github.com/ahvaan-india/ahvaan/blob/main/lib/email/send.ts): `lib/email/send.ts`
- [Database queries](https://github.com/ahvaan-india/ahvaan/blob/main/lib/db/queries.ts): `lib/db/queries.ts`
- **Postgres**
- [Redis cache](https://github.com/ahvaan-india/ahvaan/blob/main/lib/redis.ts): `lib/redis.ts`
- **Reference weather APIs**

### Other components

- **Municipal operator**

## Connections

- Municipal operator → Ward heat map: opens map
- Municipal operator → Ward analysis: selects ward
- Municipal operator → Metro overview: checks city
- Municipal operator → Alert center: reviews alerts
- Ward heat map → Kolkata map: renders wards
- Ward heat map → Heat map API: loads heat map
- Ward heat map → Ward catalogue API: loads catalogue
- Ward heat map → Telemetry API: loads telemetry
- Metro overview → City summary API: loads KPIs
- Ward analysis → Analysis API: loads analysis
- Ward analysis → Forecast API: loads forecast
- Alert center → Risk API: reads risk
- Alert center → Alert evaluation: evaluates triggers
- Alert center → Email dispatch API: dispatches advisory
- AI assistant → Chat API: sends question
- Heat map API → City board: requests board
- City summary API → City board: requests board
- City board → Database queries: reads weather and census
- City board → HeatShield engine: computes ward risk
- Heat map API → Database queries: loads ward geometry
- Heat map API → Redis cache: caches payload
- City summary API → Redis cache: caches summary
- Ward catalogue API → Database queries: loads wards
- Telemetry API → Database queries: reads ward data
- Telemetry API → HeatShield engine: computes risk
- Risk API → Database queries: reads inputs
- Risk API → HeatShield engine: builds risk response
- Forecast API → Database queries: reads inputs
- Forecast API → Forecast model: computes outlook
- Forecast API → Analysis summaries: summarizes analysis
- Forecast API → Redis cache: caches response
- Analysis API → Database queries: reads analysis rows
- Analysis API → Analysis summaries: summarizes days
- Accuracy API → Index comparison: compares indices
- Index comparison → Reference weather APIs: requests benchmarks
- Chat API → Ward chat context: builds ward context
- Chat API → Cloudflare AI: sends prompt
- Ward chat context → Database queries: reads telemetry
- Email dispatch API → Email sender: sends email
- Database queries → Postgres: reads records
- Redis cache → Postgres: falls back to queries