# bitbyob/raahnumaa-ai architecture

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

- Interactive diagram: https://gitdiagram.com/bitbyob/raahnumaa-ai
- Repository: https://github.com/bitbyob/raahnumaa-ai

## Overview

RaahNumaa AI serves Karachi traffic prediction and route planning through a Flask web app. Users submit time, weather, event, and (for routing) endpoint and mode inputs; the app returns congestion predictions, hourly batches, heatmap data, or an A*-computed route with distance, ETA, and segment details. The ML model is trained from synthetic, feature-engineered data and supplies congestion levels to routing. README-documented map visualization and navigation capabilities are included, though the template source was not provided for inspection.

Main entry points: [`app.py`](https://github.com/bitbyob/raahnumaa-ai/blob/main/app.py) (Flask routes), [`templates/index.html`](https://github.com/bitbyob/raahnumaa-ai/blob/main/templates/index.html) (Prediction UI), [`models/predictor.py`](https://github.com/bitbyob/raahnumaa-ai/blob/main/models/predictor.py) (Traffic prediction), [`routing/astar.py`](https://github.com/bitbyob/raahnumaa-ai/blob/main/routing/astar.py) (A* route search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_flask["Flask routes<br/>[app.py]"]
  node_phase1ui["Prediction UI<br/>[index.html]"]
  node_phase2ui["Route map UI<br/>[phase2.html]"]
  node_routevisualization["Route visualization<br/>[phase2.html]"]
  node_heatmap["Congestion heatmap<br/>[app.py]"]
  node_batch["Hourly predictions<br/>[app.py]"]
end

subgraph group_prediction["Traffic prediction"]
  node_congestion["Traffic prediction<br/>[predictor.py]"]
  node_modelstate[("Trained model files")]
end

subgraph group_routing["Route optimization"]
  node_trafficmap["Node traffic map<br/>[astar.py]"]
  node_roadgraph["Karachi road network<br/>[karachi_graph.py]"]
  node_astar["A* route search<br/>[astar.py]"]
end

subgraph group_data["Traffic data"]
  node_trainingdata["Synthetic data generator<br/>[generate_data.py]"]
  node_csvdata["Generated traffic data<br/>[traffic_data.csv]"]
end

node_traveler(("Web user"))

node_traveler -->|"uses"| node_phase1ui
node_traveler -->|"uses"| node_phase2ui
node_phase1ui -.->|"submits inputs"| node_flask
node_phase2ui -.->|"requests routes"| node_flask
node_flask -->|"predicts traffic"| node_congestion
node_flask -->|"re-trains"| node_congestion
node_flask -->|"builds graph"| node_roadgraph
node_flask -->|"builds traffic map"| node_trafficmap
node_flask -->|"searches route"| node_astar
node_flask -->|"generates hourly data"| node_batch
node_flask -->|"generates grid data"| node_heatmap
node_flask -->|"renders"| node_phase1ui
node_flask -->|"renders"| node_phase2ui
node_congestion -->|"generates training data"| node_trainingdata
node_congestion -->|"loads and saves"| node_modelstate
node_trainingdata -->|"writes CSV"| node_csvdata
node_trafficmap -->|"predicts per node"| node_congestion
node_astar -->|"reads network"| node_roadgraph
node_astar -->|"weights by congestion"| node_trafficmap
node_astar -->|"returns route details"| node_routevisualization
node_phase2ui -->|"shows map"| node_routevisualization
node_phase1ui -.->|"shows hourly chart"| node_batch
node_phase1ui -.->|"shows heatmap"| node_heatmap

click node_flask "https://github.com/bitbyob/raahnumaa-ai/blob/main/app.py"
click node_phase1ui "https://github.com/bitbyob/raahnumaa-ai/blob/main/templates/index.html"
click node_phase2ui "https://github.com/bitbyob/raahnumaa-ai/blob/main/templates/phase2.html"
click node_congestion "https://github.com/bitbyob/raahnumaa-ai/blob/main/models/predictor.py"
click node_modelstate "https://github.com/bitbyob/raahnumaa-ai/tree/main/models"
click node_trainingdata "https://github.com/bitbyob/raahnumaa-ai/blob/main/data/generate_data.py"
click node_csvdata "https://github.com/bitbyob/raahnumaa-ai/blob/main/data/traffic_data.csv"
click node_trafficmap "https://github.com/bitbyob/raahnumaa-ai/blob/main/routing/astar.py"
click node_roadgraph "https://github.com/bitbyob/raahnumaa-ai/blob/main/routing/karachi_graph.py"
click node_astar "https://github.com/bitbyob/raahnumaa-ai/blob/main/routing/astar.py"
click node_routevisualization "https://github.com/bitbyob/raahnumaa-ai/blob/main/templates/phase2.html"
click node_heatmap "https://github.com/bitbyob/raahnumaa-ai/blob/main/app.py"
click node_batch "https://github.com/bitbyob/raahnumaa-ai/blob/main/app.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_flask,node_phase1ui,node_phase2ui,node_routevisualization,node_heatmap,node_batch,node_traveler toneBlue
class node_congestion,node_modelstate toneAmber
class node_trafficmap,node_roadgraph,node_astar toneMint
class node_trainingdata,node_csvdata toneRose
```

## Components

### Web application

- [Flask routes](https://github.com/bitbyob/raahnumaa-ai/blob/main/app.py): `app.py`
- [Prediction UI](https://github.com/bitbyob/raahnumaa-ai/blob/main/templates/index.html): `templates/index.html`
- [Route map UI](https://github.com/bitbyob/raahnumaa-ai/blob/main/templates/phase2.html): `templates/phase2.html`
- [Route visualization](https://github.com/bitbyob/raahnumaa-ai/blob/main/templates/phase2.html): `templates/phase2.html`
- [Congestion heatmap](https://github.com/bitbyob/raahnumaa-ai/blob/main/app.py): `app.py`
- [Hourly predictions](https://github.com/bitbyob/raahnumaa-ai/blob/main/app.py): `app.py`

### Traffic prediction

- [Traffic prediction](https://github.com/bitbyob/raahnumaa-ai/blob/main/models/predictor.py): `models/predictor.py`
- [Trained model files](https://github.com/bitbyob/raahnumaa-ai/tree/main/models): `models`

### Route optimization

- [Node traffic map](https://github.com/bitbyob/raahnumaa-ai/blob/main/routing/astar.py): `routing/astar.py`
- [Karachi road network](https://github.com/bitbyob/raahnumaa-ai/blob/main/routing/karachi_graph.py): `routing/karachi_graph.py`
- [A* route search](https://github.com/bitbyob/raahnumaa-ai/blob/main/routing/astar.py): `routing/astar.py`

### Traffic data

- [Synthetic data generator](https://github.com/bitbyob/raahnumaa-ai/blob/main/data/generate_data.py): `data/generate_data.py`
- [Generated traffic data](https://github.com/bitbyob/raahnumaa-ai/blob/main/data/traffic_data.csv): `data/traffic_data.csv`

### Other components

- **Web user**

## Connections

- Web user → Prediction UI: uses (evidence: `README.md`)
- Web user → Route map UI: uses (evidence: `README.md`)
- Prediction UI → Flask routes: submits inputs
- Route map UI → Flask routes: requests routes
- Flask routes → Traffic prediction: predicts traffic (evidence: `app.py`)
- Flask routes → Traffic prediction: re-trains (evidence: `app.py`)
- Flask routes → Karachi road network: builds graph (evidence: `app.py`)
- Flask routes → Node traffic map: builds traffic map (evidence: `app.py`)
- Flask routes → A* route search: searches route (evidence: `app.py`)
- Flask routes → Hourly predictions: generates hourly data (evidence: `app.py`)
- Flask routes → Congestion heatmap: generates grid data (evidence: `app.py`)
- Flask routes → Prediction UI: renders (evidence: `app.py`)
- Flask routes → Route map UI: renders (evidence: `app.py`)
- Traffic prediction → Synthetic data generator: generates training data (evidence: `models/predictor.py`)
- Traffic prediction → Trained model files: loads and saves (evidence: `models/predictor.py`)
- Synthetic data generator → Generated traffic data: writes CSV (evidence: `data/generate_data.py`)
- Node traffic map → Traffic prediction: predicts per node (evidence: `routing/astar.py`)
- A* route search → Karachi road network: reads network (evidence: `routing/astar.py`)
- A* route search → Node traffic map: weights by congestion (evidence: `routing/astar.py`)
- A* route search → Route visualization: returns route details (evidence: `README.md`)
- Route map UI → Route visualization: shows map (evidence: `README.md`)
- Prediction UI → Hourly predictions: shows hourly chart
- Prediction UI → Congestion heatmap: shows heatmap
