# teja992005/routecaste-digitaltwin architecture

> Architecture diagram of the GitHub repository teja992005/routecaste-digitaltwin, 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/teja992005/routecaste-digitaltwin
- Repository: https://github.com/teja992005/routecaste-digitaltwin

## Overview

RouteCast is a browser-based route-intelligence prototype with two principal experiences: synthetic-graph event planning and real-world directions enriched with route intelligence. The graph preserves both workflows, navigation progress, map and analytics capabilities, optional ML, Guntur routing, and the presentation experience. Edges reflect README descriptions and the supplied source index or excerpts; some UI-to-API and unsampled Guntur links are documented or marked unverified rather than inferred from names.

Main entry points: [`app/page.tsx`](https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/page.tsx) (RouteCast app), [`app/api/plan/route.ts`](https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/plan/route.ts) (Event planning API), [`app/api/intelligence/route/route.ts`](https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/intelligence/route/route.ts) (Intelligence API), [`components/navigation-panel.tsx`](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/navigation-panel.tsx) (Directions panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser experience"]
  node_app["RouteCast app<br/>[page.tsx]"]
  node_map["Interactive map<br/>[city-map.tsx]"]
  node_dash["Analytics panels"]
  node_scenario["Scenario controls<br/>[scenario-panel.tsx]"]
  node_comparison["Route comparison"]
  node_forecast["Forecast display<br/>[forecast-strip.tsx]"]
  node_holo2d["2D visualization<br/>[hologram-2d.tsx]"]
  node_holo3d["3D visualization<br/>[hologram-3d.tsx]"]
  node_directionsui["Directions panel"]
  node_search["Location search"]
  node_intelui["Route intelligence panel"]
end

subgraph group_event["Event simulation"]
  node_planapi["Event planning API<br/>[route.ts]"]
  node_city["Synthetic city graph<br/>[city.ts]"]
  node_optimizer["Dijkstra optimizer<br/>[optimizer.ts]"]
  node_simulation["Scenario simulation<br/>[sim.ts]"]
  node_eventstore[("Event state<br/>[store.ts]")]
end

subgraph group_directions["Directions and intelligence"]
  node_geocodeapi["Geocoding API<br/>[route.ts]"]
  node_geocoder["Nominatim geocoder<br/>[geocoder.ts]"]
  node_navapi["Navigation API<br/>[route.ts]"]
  node_routing["OSRM routing<br/>[routing.ts]"]
  node_intelapi["Intelligence API<br/>[route.ts]"]
  node_scoring["Route scoring<br/>[score.ts]"]
  node_incidents[("Incident intelligence<br/>[incidents.ts]")]
  node_weather["Weather enrichment<br/>[weather.ts]"]
  node_ml["Optional ML inference<br/>[ml.ts]"]
end

subgraph group_support["Navigation and integrations"]
  node_geo["Browser geolocation<br/>[use-geolocation.ts]"]
  node_navsession["Navigation session<br/>[use-nav-session.ts]"]
  node_progress["Route progress math<br/>[progress.ts]"]
  node_placesapi["Nearby places API<br/>[route.ts]"]
  node_places["Nearby POI lookup<br/>[places.ts]"]
end

subgraph group_extras["Additional capabilities"]
  node_gunturapi["Guntur route API<br/>[route.ts]"]
  node_guntur["Guntur routing data<br/>[guntur.ts]"]
  node_presentation["Presentation experience<br/>[slides.tsx]"]
end

node_user(("User / browser"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_map
node_app -->|"renders"| node_dash
node_app -->|"renders"| node_scenario
node_app -->|"renders"| node_comparison
node_app -->|"renders"| node_forecast
node_app -->|"requests plans"| node_planapi
node_planapi -->|"builds graph"| node_city
node_planapi -->|"plans routes"| node_optimizer
node_planapi -->|"applies scenarios"| node_simulation
node_planapi -->|"loads event"| node_eventstore
node_planapi -->|"reranks routes"| node_ml
node_app -->|"renders"| node_holo2d
node_app -->|"renders"| node_holo3d
node_user -->|"searches places"| node_search
node_search -.->|"requests geocoding"| node_geocodeapi
node_geocodeapi -->|"geocodes"| node_geocoder
node_user -->|"sets trip"| node_directionsui
node_directionsui -.->|"requests route"| node_navapi
node_navapi -->|"gets routes"| node_routing
node_intelui -.->|"requests analysis"| node_intelapi
node_intelapi -->|"gets candidates"| node_routing
node_intelapi -->|"fetches weather"| node_weather
node_intelapi -->|"loads incidents"| node_incidents
node_intelapi -->|"scores routes"| node_scoring
node_scoring -->|"predicts ETA"| node_ml
node_scoring -->|"analyses impact"| node_incidents
node_scoring -->|"uses rain feature"| node_weather
node_directionsui -->|"gets position"| node_geo
node_directionsui -->|"tracks trip"| node_navsession
node_navsession -->|"computes progress"| node_progress
node_user -.->|"finds nearby POIs"| node_placesapi
node_placesapi -->|"looks up places"| node_places
node_user -.->|"requests Guntur route"| node_gunturapi
node_gunturapi -->|"uses route data"| node_guntur
node_user -->|"views presentation"| node_presentation

click node_app "https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/page.tsx"
click node_map "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/city-map.tsx"
click node_dash "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/metrics-dashboard.tsx"
click node_scenario "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/scenario-panel.tsx"
click node_comparison "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/comparison-table.tsx"
click node_forecast "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/forecast-strip.tsx"
click node_holo2d "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/hologram-2d.tsx"
click node_holo3d "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/hologram-3d.tsx"
click node_planapi "https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/plan/route.ts"
click node_city "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/city.ts"
click node_optimizer "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/optimizer.ts"
click node_simulation "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/sim.ts"
click node_eventstore "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/store.ts"
click node_directionsui "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/navigation-panel.tsx"
click node_search "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/location-search.tsx"
click node_geocodeapi "https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/geocode/route.ts"
click node_geocoder "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/geo/geocoder.ts"
click node_navapi "https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/navigation/route/route.ts"
click node_routing "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/geo/routing.ts"
click node_intelui "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/route-intel-panel.tsx"
click node_intelapi "https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/intelligence/route/route.ts"
click node_scoring "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/intel/score.ts"
click node_incidents "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/intel/incidents.ts"
click node_weather "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/intel/weather.ts"
click node_ml "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/ml.ts"
click node_geo "https://github.com/teja992005/routecaste-digitaltwin/blob/main/hooks/use-geolocation.ts"
click node_navsession "https://github.com/teja992005/routecaste-digitaltwin/blob/main/hooks/use-nav-session.ts"
click node_progress "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/nav/progress.ts"
click node_placesapi "https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/places/nearby/route.ts"
click node_places "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/geo/places.ts"
click node_gunturapi "https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/guntur/route.ts"
click node_guntur "https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/guntur.ts"
click node_presentation "https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/presentation/slides.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_app,node_map,node_dash,node_scenario,node_comparison,node_forecast,node_holo2d,node_holo3d,node_directionsui,node_search,node_intelui,node_user toneBlue
class node_planapi,node_city,node_optimizer,node_simulation,node_eventstore toneAmber
class node_geocodeapi,node_geocoder,node_navapi,node_routing,node_intelapi,node_scoring,node_incidents,node_weather,node_ml toneMint
class node_geo,node_navsession,node_progress,node_placesapi,node_places toneRose
class node_gunturapi,node_guntur,node_presentation toneIndigo
```

## Components

### Browser experience

- [RouteCast app](https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/page.tsx): `app/page.tsx`
- [Interactive map](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/city-map.tsx): `components/city-map.tsx`
- [Analytics panels](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/metrics-dashboard.tsx): `components/metrics-dashboard.tsx`
- [Scenario controls](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/scenario-panel.tsx): `components/scenario-panel.tsx`
- [Route comparison](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/comparison-table.tsx): `components/comparison-table.tsx`
- [Forecast display](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/forecast-strip.tsx): `components/forecast-strip.tsx`
- [2D visualization](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/hologram-2d.tsx): `components/hologram-2d.tsx`
- [3D visualization](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/hologram-3d.tsx): `components/hologram-3d.tsx`
- [Directions panel](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/navigation-panel.tsx): `components/navigation-panel.tsx`
- [Location search](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/location-search.tsx): `components/location-search.tsx`
- [Route intelligence panel](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/route-intel-panel.tsx): `components/route-intel-panel.tsx`

### Event simulation

- [Event planning API](https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/plan/route.ts): `app/api/plan/route.ts`
- [Synthetic city graph](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/city.ts): `lib/city.ts`
- [Dijkstra optimizer](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/optimizer.ts): `lib/optimizer.ts`
- [Scenario simulation](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/sim.ts): `lib/sim.ts`
- [Event state](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/store.ts): `lib/store.ts`

### Directions and intelligence

- [Geocoding API](https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/geocode/route.ts): `app/api/geocode/route.ts`
- [Nominatim geocoder](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/geo/geocoder.ts): `lib/geo/geocoder.ts`
- [Navigation API](https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/navigation/route/route.ts): `app/api/navigation/route/route.ts`
- [OSRM routing](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/geo/routing.ts): `lib/geo/routing.ts`
- [Intelligence API](https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/intelligence/route/route.ts): `app/api/intelligence/route/route.ts`
- [Route scoring](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/intel/score.ts): `lib/intel/score.ts`
- [Incident intelligence](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/intel/incidents.ts): `lib/intel/incidents.ts`
- [Weather enrichment](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/intel/weather.ts): `lib/intel/weather.ts`
- [Optional ML inference](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/ml.ts): `lib/ml.ts`

### Navigation and integrations

- [Browser geolocation](https://github.com/teja992005/routecaste-digitaltwin/blob/main/hooks/use-geolocation.ts): `hooks/use-geolocation.ts`
- [Navigation session](https://github.com/teja992005/routecaste-digitaltwin/blob/main/hooks/use-nav-session.ts): `hooks/use-nav-session.ts`
- [Route progress math](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/nav/progress.ts): `lib/nav/progress.ts`
- [Nearby places API](https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/places/nearby/route.ts): `app/api/places/nearby/route.ts`
- [Nearby POI lookup](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/geo/places.ts): `lib/geo/places.ts`

### Additional capabilities

- [Guntur route API](https://github.com/teja992005/routecaste-digitaltwin/blob/main/app/api/guntur/route.ts): `app/api/guntur/route.ts`
- [Guntur routing data](https://github.com/teja992005/routecaste-digitaltwin/blob/main/lib/guntur.ts): `lib/guntur.ts`
- [Presentation experience](https://github.com/teja992005/routecaste-digitaltwin/blob/main/components/presentation/slides.tsx): `components/presentation/slides.tsx`

### Other components

- **User / browser**

## Connections

- User / browser → RouteCast app: uses
- RouteCast app → Interactive map: renders (evidence: `app/page.tsx`)
- RouteCast app → Analytics panels: renders (evidence: `app/page.tsx`)
- RouteCast app → Scenario controls: renders (evidence: `app/page.tsx`)
- RouteCast app → Route comparison: renders (evidence: `app/page.tsx`)
- RouteCast app → Forecast display: renders (evidence: `app/page.tsx`)
- RouteCast app → Event planning API: requests plans
- Event planning API → Synthetic city graph: builds graph (evidence: `app/api/plan/route.ts`)
- Event planning API → Dijkstra optimizer: plans routes (evidence: `app/api/plan/route.ts`)
- Event planning API → Scenario simulation: applies scenarios (evidence: `app/api/plan/route.ts`)
- Event planning API → Event state: loads event (evidence: `app/api/plan/route.ts`)
- Event planning API → Optional ML inference: reranks routes (evidence: `app/api/plan/route.ts`)
- RouteCast app → 2D visualization: renders (evidence: `app/page.tsx`)
- RouteCast app → 3D visualization: renders (evidence: `app/page.tsx`)
- User / browser → Location search: searches places
- Location search → Geocoding API: requests geocoding
- Geocoding API → Nominatim geocoder: geocodes (evidence: `app/api/geocode/route.ts`)
- User / browser → Directions panel: sets trip
- Directions panel → Navigation API: requests route
- Navigation API → OSRM routing: gets routes (evidence: `app/api/navigation/route/route.ts`)
- Route intelligence panel → Intelligence API: requests analysis
- Intelligence API → OSRM routing: gets candidates (evidence: `app/api/intelligence/route/route.ts`)
- Intelligence API → Weather enrichment: fetches weather (evidence: `app/api/intelligence/route/route.ts`)
- Intelligence API → Incident intelligence: loads incidents (evidence: `app/api/intelligence/route/route.ts`)
- Intelligence API → Route scoring: scores routes (evidence: `app/api/intelligence/route/route.ts`)
- Route scoring → Optional ML inference: predicts ETA (evidence: `lib/intel/score.ts`)
- Route scoring → Incident intelligence: analyses impact (evidence: `lib/intel/score.ts`)
- Route scoring → Weather enrichment: uses rain feature (evidence: `lib/intel/score.ts`)
- Directions panel → Browser geolocation: gets position (evidence: `components/navigation-panel.tsx`)
- Directions panel → Navigation session: tracks trip (evidence: `components/navigation-panel.tsx`)
- Navigation session → Route progress math: computes progress (evidence: `hooks/use-nav-session.ts`)
- User / browser → Nearby places API: finds nearby POIs
- Nearby places API → Nearby POI lookup: looks up places (evidence: `app/api/places/nearby/route.ts`)
- User / browser → Guntur route API: requests Guntur route
- Guntur route API → Guntur routing data: uses route data (evidence: `app/api/guntur/route.ts`)
- User / browser → Presentation experience: views presentation