# uday-mahajan-dev/cycloneguard architecture

> Architecture diagram of the GitHub repository uday-mahajan-dev/cycloneguard, 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/uday-mahajan-dev/cycloneguard
- Repository: https://github.com/uday-mahajan-dev/cycloneguard

## Overview

CycloneGuard is a cyclone early-warning and disaster-response platform with a web operations dashboard and a FastAPI/PostGIS backend. The principal workflow is to review storm conditions, simulate coastal surge and inundation, assess exposed infrastructure, and use the resulting intelligence for response and insurance decisions. The tree also indicates live marine, alerting, and AI capabilities. README content and most service/router implementations were not provided, so uncertain internal call relationships are omitted.

Main entry points: [`backend/main.py`](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/main.py) (FastAPI application), [`backend/routers/infrastructure.py`](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/infrastructure.py) (Infrastructure endpoints), [`frontend/app/dashboard/page.tsx`](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/app/dashboard/page.tsx) (Operations dashboard), [`frontend/components/map/MapContainer.tsx`](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/components/map/MapContainer.tsx) (Storm and asset map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Operations interface"]
  node_dashboard["Operations dashboard<br/>[page.tsx]"]
  node_map["Storm and asset map<br/>[MapContainer.tsx]"]
  node_radar["Radar tile hook"]
  node_stormstore["Storm state<br/>[useStormStore.ts]"]
  node_api_client["Frontend API client<br/>[api.ts]"]
end

subgraph group_api["API and orchestration"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_storm_router["Storm endpoints<br/>[storm.py]"]
  node_surge_router["Surge endpoints<br/>[surge.py]"]
  node_infra_router["Infrastructure endpoints<br/>[infrastructure.py]"]
  node_gemini_router["AI endpoints<br/>[gemini.py]"]
  node_alerts_router["Alert endpoints<br/>[alerts.py]"]
  node_insurance_router["Insurance endpoints<br/>[insurance.py]"]
end

subgraph group_hazard["Hazard intelligence"]
  node_storm_fetch["Storm data fetch<br/>[storm_fetcher.py]"]
  node_marine_fetch["Marine data fetch<br/>[marine_fetcher.py]"]
  node_surge_model["Surge simulation<br/>[surge_model.py]"]
  node_gee["Geospatial processing<br/>[gee_processor.py]"]
end

subgraph group_response["Response and risk"]
  node_infra_query["Exposure analysis"]
  node_osm["OSM asset loader<br/>[osm_loader.py]"]
  node_gemini["AI analysis<br/>[gemini_agent.py]"]
  node_dispatcher["Alert dispatch"]
end

subgraph group_state["Persistence and shared data"]
  node_db[("PostGIS database<br/>[connection.py]")]
  node_http["Shared HTTP client<br/>[http_client.py]"]
end

node_operator(("Operator"))
node_rainviewer["RainViewer"]
node_overpass["OSM Overpass"]

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"requests data"| node_api_client
node_dashboard -->|"updates state"| node_stormstore
node_dashboard -->|"renders map"| node_map
node_map -->|"loads radar"| node_radar
node_radar -.->|"fetches tiles"| node_rainviewer
node_backend -->|"mounts routes"| node_storm_router
node_backend -->|"mounts routes"| node_surge_router
node_backend -->|"mounts routes"| node_infra_router
node_backend -->|"mounts routes"| node_gemini_router
node_backend -->|"mounts routes"| node_alerts_router
node_backend -->|"mounts routes"| node_insurance_router
node_infra_router -->|"runs exposure"| node_infra_query
node_infra_router -->|"queries assets"| node_db
node_infra_router -->|"uses client"| node_http
node_infra_router -.->|"fetches assets"| node_overpass
node_backend -->|"checks connection"| node_db
node_backend -->|"initializes client"| node_http

click node_dashboard "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/app/dashboard/page.tsx"
click node_map "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/components/map/MapContainer.tsx"
click node_radar "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/hooks/useRainViewerTiles.ts"
click node_stormstore "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/lib/stores/useStormStore.ts"
click node_api_client "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/lib/api.ts"
click node_backend "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/main.py"
click node_storm_router "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/storm.py"
click node_surge_router "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/surge.py"
click node_infra_router "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/infrastructure.py"
click node_gemini_router "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/gemini.py"
click node_alerts_router "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/alerts.py"
click node_insurance_router "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/insurance.py"
click node_storm_fetch "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/storm_fetcher.py"
click node_marine_fetch "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/marine_fetcher.py"
click node_surge_model "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/surge_model.py"
click node_gee "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/gee_processor.py"
click node_infra_query "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/infrastructure_query.py"
click node_osm "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/osm_loader.py"
click node_gemini "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/gemini_agent.py"
click node_dispatcher "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/alert_dispatcher.py"
click node_db "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/db/connection.py"
click node_http "https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/utils/http_client.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_dashboard,node_map,node_radar,node_stormstore,node_api_client,node_rainviewer toneBlue
class node_backend,node_storm_router,node_surge_router,node_infra_router,node_gemini_router,node_alerts_router,node_insurance_router toneAmber
class node_storm_fetch,node_marine_fetch,node_surge_model,node_gee toneMint
class node_infra_query,node_osm,node_gemini,node_dispatcher toneRose
class node_db,node_http,node_operator,node_overpass toneIndigo
```

## Components

### Operations interface

- [Operations dashboard](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Storm and asset map](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/components/map/MapContainer.tsx): `frontend/components/map/MapContainer.tsx`
- [Radar tile hook](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/hooks/useRainViewerTiles.ts): `frontend/hooks/useRainViewerTiles.ts`
- [Storm state](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/lib/stores/useStormStore.ts): `frontend/lib/stores/useStormStore.ts`
- [Frontend API client](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API and orchestration

- [FastAPI application](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/main.py): `backend/main.py`
- [Storm endpoints](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/storm.py): `backend/routers/storm.py`
- [Surge endpoints](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/surge.py): `backend/routers/surge.py`
- [Infrastructure endpoints](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/infrastructure.py): `backend/routers/infrastructure.py`
- [AI endpoints](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/gemini.py): `backend/routers/gemini.py`
- [Alert endpoints](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/alerts.py): `backend/routers/alerts.py`
- [Insurance endpoints](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/routers/insurance.py): `backend/routers/insurance.py`

### Hazard intelligence

- [Storm data fetch](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/storm_fetcher.py): `backend/services/storm_fetcher.py`
- [Marine data fetch](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/marine_fetcher.py): `backend/services/marine_fetcher.py`
- [Surge simulation](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/surge_model.py): `backend/services/surge_model.py`
- [Geospatial processing](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/gee_processor.py): `backend/services/gee_processor.py`

### Response and risk

- [Exposure analysis](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/infrastructure_query.py): `backend/services/infrastructure_query.py`
- [OSM asset loader](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/osm_loader.py): `backend/services/osm_loader.py`
- [AI analysis](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/gemini_agent.py): `backend/services/gemini_agent.py`
- [Alert dispatch](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/services/alert_dispatcher.py): `backend/services/alert_dispatcher.py`

### Persistence and shared data

- [PostGIS database](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/db/connection.py): `backend/db/connection.py`
- [Shared HTTP client](https://github.com/uday-mahajan-dev/cycloneguard/blob/main/backend/utils/http_client.py): `backend/utils/http_client.py`

### Other components

- **Operator**
- **RainViewer**
- **OSM Overpass**

## Connections

- Operator → Operations dashboard: uses
- Operations dashboard → Frontend API client: requests data
- Operations dashboard → Storm state: updates state
- Operations dashboard → Storm and asset map: renders map
- Storm and asset map → Radar tile hook: loads radar
- Radar tile hook → RainViewer: fetches tiles
- FastAPI application → Storm endpoints: mounts routes
- FastAPI application → Surge endpoints: mounts routes
- FastAPI application → Infrastructure endpoints: mounts routes
- FastAPI application → AI endpoints: mounts routes
- FastAPI application → Alert endpoints: mounts routes
- FastAPI application → Insurance endpoints: mounts routes
- Infrastructure endpoints → Exposure analysis: runs exposure
- Infrastructure endpoints → PostGIS database: queries assets
- Infrastructure endpoints → Shared HTTP client: uses client
- Infrastructure endpoints → OSM Overpass: fetches assets
- FastAPI application → PostGIS database: checks connection
- FastAPI application → Shared HTTP client: initializes client