# dope-otaku/geospatial-demand-forecaster architecture

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

- Interactive diagram: https://gitdiagram.com/dope-otaku/geospatial-demand-forecaster
- Repository: https://github.com/dope-otaku/geospatial-demand-forecaster

## Overview

Geo-Demand AI simulates a Mumbai delivery fleet, streams rider coordinates through Kafka, clusters recent positions in a FastAPI service, and displays the live stream and demand visualizations in a web dashboard. The producer creates stateful riders; the backend consumes events and periodically attaches K-Means centroids before forwarding events over WebSockets. The dashboard tracks fleet metrics and renders rider, centroid, and hexagon layers with hover details. Backend and frontend relationships are supported by the excerpts; broader operational details are described in the README.

Main entry points: [`backend/main.py`](https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/backend/main.py) (Stream Service), [`frontend/geospatial-demand-forecaster/src/app/page.tsx`](https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/frontend/geospatial-demand-forecaster/src/app/page.tsx) (Live Dashboard), [`data-pipeline/producer.py`](https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/data-pipeline/producer.py) (Rider Simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Fleet Simulation"]
  node_producer["Rider Simulator<br/>[producer.py]"]
end

subgraph group_streaming["Event Streaming"]
  node_kafka["Kafka Topic"]
  node_backend["Stream Service<br/>[main.py]"]
end

subgraph group_analytics["Demand Analytics"]
  node_predictor["Demand Predictor<br/>[main.py]"]
end

subgraph group_dashboard["Live Dashboard"]
  node_dashboard["Live Dashboard<br/>[page.tsx]"]
end

node_maptiles["Map Tiles"]
node_operator(("Dashboard Viewer"))

node_producer -->|"publishes events"| node_kafka
node_kafka -->|"consumes events"| node_backend
node_backend -->|"updates and queries"| node_predictor
node_backend -->|"streams WebSocket data"| node_dashboard
node_dashboard -->|"loads map style"| node_maptiles
node_operator -.->|"views"| node_dashboard

click node_producer "https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/data-pipeline/producer.py"
click node_backend "https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/backend/main.py"
click node_predictor "https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/backend/main.py"
click node_dashboard "https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/frontend/geospatial-demand-forecaster/src/app/page.tsx"

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_producer,node_operator toneBlue
class node_kafka,node_backend toneAmber
class node_predictor toneMint
class node_dashboard toneRose
class node_maptiles toneIndigo
```

## Components

### Fleet Simulation

- [Rider Simulator](https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/data-pipeline/producer.py): `data-pipeline/producer.py`

### Event Streaming

- **Kafka Topic**
- [Stream Service](https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/backend/main.py): `backend/main.py`

### Demand Analytics

- [Demand Predictor](https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/backend/main.py): `backend/main.py`

### Live Dashboard

- [Live Dashboard](https://github.com/dope-otaku/geospatial-demand-forecaster/blob/main/frontend/geospatial-demand-forecaster/src/app/page.tsx): `frontend/geospatial-demand-forecaster/src/app/page.tsx`

### Other components

- **Map Tiles**
- **Dashboard Viewer**

## Connections

- Rider Simulator → Kafka Topic: publishes events (evidence: `data-pipeline/producer.py`)
- Kafka Topic → Stream Service: consumes events (evidence: `backend/main.py`)
- Stream Service → Demand Predictor: updates and queries (evidence: `backend/main.py`)
- Stream Service → Live Dashboard: streams WebSocket data (evidence: `frontend/geospatial-demand-forecaster/src/app/page.tsx`)
- Live Dashboard → Map Tiles: loads map style (evidence: `frontend/geospatial-demand-forecaster/src/app/page.tsx`)
- Dashboard Viewer → Live Dashboard: views
