# akashdesai93/routeiq architecture

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

- Interactive diagram: https://gitdiagram.com/akashdesai93/routeiq
- Repository: https://github.com/akashdesai93/routeiq

## Overview

RouteIQ is a trip-planning and driving app: users choose or search for endpoints, compare traffic-aware routes with signal counts, then simulate or follow a route with live guidance and rerouting. The map presents routes and drive state; device adapters provide location, speech, and native-shell services. The README documents these capabilities, while excerpts show key route, signal-data, and map relationships. The repository also contains a reusable design kit; its internal runtime wiring is only lightly represented here.

Main entry points: [`src/App.tsx`](https://github.com/akashdesai93/routeiq/blob/main/src/App.tsx) (App orchestration), [`src/signalData.ts`](https://github.com/akashdesai93/routeiq/blob/main/src/signalData.ts) (Signal data loader), [`src/useRoutes.ts`](https://github.com/akashdesai93/routeiq/blob/main/src/useRoutes.ts) (Route planning), [`src/drive/freshRoutes.ts`](https://github.com/akashdesai93/routeiq/blob/main/src/drive/freshRoutes.ts) (Fresh route checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Trip planning"]
  node_app["App orchestration<br/>[App.tsx]"]
  node_planning_ui["Trip controls<br/>[PlanPanel.tsx]"]
  node_place_search["Place search<br/>[usePlaceSearch.ts]"]
  node_route_hook["Route planning<br/>[useRoutes.ts]"]
end

subgraph group_drive["Routing and driving"]
  node_core["Route domain core<br/>[geo.ts]"]
  node_mapbox["Mapbox directions<br/>[client.ts]"]
  node_rank["Route ranking<br/>[rank.ts]"]
  node_fresh_routes["Fresh route checks<br/>[freshRoutes.ts]"]
  node_simulation["Drive simulation<br/>[simulation.ts]"]
  node_live["Live guidance<br/>[live.ts]"]
  node_guidance["Turn guidance<br/>[guidance.ts]"]
end

subgraph group_mapdata["Map and signal data"]
  node_mapview["Route map<br/>[MapView.tsx]"]
  node_drive_features["Drive map features<br/>[driveFeatures.ts]"]
  node_signal_data["Signal data loader<br/>[signalData.ts]"]
  node_osm["Overpass signals<br/>[client.ts]"]
  node_signal_store[("Signal tile cache<br/>[kv.ts]")]
end

subgraph group_device["Device services"]
  node_device_api["Device location<br/>[geolocation.ts]"]
  node_native["Native shell bridge<br/>[index.ts]"]
end

subgraph group_design["Design kit"]
  node_kit_stage["Stage runtime<br/>[stage.tsx]"]
  node_kit_actions["Action scripts<br/>[act.ts]"]
  node_kit_cursor["Cursor behavior<br/>[cursor.tsx]"]
  node_kit_measure["Geometry utilities<br/>[measure.ts]"]
end

node_driver(("Driver"))

node_driver -->|"plans and drives"| node_app
node_app -->|"presents trip controls"| node_planning_ui
node_planning_ui -.->|"searches places"| node_place_search
node_planning_ui -.->|"requests routes"| node_route_hook
node_route_hook -->|"fetches directions"| node_mapbox
node_route_hook -->|"loads signal counts"| node_signal_data
node_route_hook -->|"ranks routes"| node_core
node_mapbox -->|"parses directions"| node_core
node_app -.->|"shows trip map"| node_mapview
node_mapview -->|"builds drive features"| node_drive_features
node_signal_data -->|"requests missing tiles"| node_osm
node_signal_data -->|"caches tiles"| node_signal_store
node_osm -->|"returns signal tiles"| node_signal_data
node_mapview -.->|"displays routes"| node_driver
node_fresh_routes -->|"checks fresh routes"| node_mapbox
node_fresh_routes -->|"counts fresh signals"| node_signal_data
node_fresh_routes -->|"applies simulated delay"| node_simulation
node_app -.->|"starts live drive"| node_live
node_live -.->|"produces turn prompts"| node_guidance
node_app -->|"configures shell services"| node_native
node_native -->|"uses device location"| node_device_api
node_kit_stage -->|"plays scripts"| node_kit_actions
node_kit_stage -->|"uses cursor behavior"| node_kit_cursor
node_kit_stage -->|"uses geometry"| node_kit_measure

click node_app "https://github.com/akashdesai93/routeiq/blob/main/src/App.tsx"
click node_planning_ui "https://github.com/akashdesai93/routeiq/blob/main/src/PlanPanel.tsx"
click node_place_search "https://github.com/akashdesai93/routeiq/blob/main/src/usePlaceSearch.ts"
click node_route_hook "https://github.com/akashdesai93/routeiq/blob/main/src/useRoutes.ts"
click node_core "https://github.com/akashdesai93/routeiq/blob/main/src/core/geo.ts"
click node_mapbox "https://github.com/akashdesai93/routeiq/blob/main/src/providers/mapbox/client.ts"
click node_rank "https://github.com/akashdesai93/routeiq/blob/main/src/core/rank.ts"
click node_fresh_routes "https://github.com/akashdesai93/routeiq/blob/main/src/drive/freshRoutes.ts"
click node_simulation "https://github.com/akashdesai93/routeiq/blob/main/src/drive/simulation.ts"
click node_live "https://github.com/akashdesai93/routeiq/blob/main/src/core/live.ts"
click node_guidance "https://github.com/akashdesai93/routeiq/blob/main/src/core/guidance.ts"
click node_mapview "https://github.com/akashdesai93/routeiq/blob/main/src/map/MapView.tsx"
click node_drive_features "https://github.com/akashdesai93/routeiq/blob/main/src/map/driveFeatures.ts"
click node_signal_data "https://github.com/akashdesai93/routeiq/blob/main/src/signalData.ts"
click node_osm "https://github.com/akashdesai93/routeiq/blob/main/src/providers/osm/client.ts"
click node_signal_store "https://github.com/akashdesai93/routeiq/blob/main/src/storage/kv.ts"
click node_device_api "https://github.com/akashdesai93/routeiq/blob/main/src/device/geolocation.ts"
click node_native "https://github.com/akashdesai93/routeiq/blob/main/src/device/native/index.ts"
click node_kit_stage "https://github.com/akashdesai93/routeiq/blob/main/design/kit/stage.tsx"
click node_kit_actions "https://github.com/akashdesai93/routeiq/blob/main/design/kit/act.ts"
click node_kit_cursor "https://github.com/akashdesai93/routeiq/blob/main/design/kit/cursor.tsx"
click node_kit_measure "https://github.com/akashdesai93/routeiq/blob/main/design/kit/measure.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_app,node_planning_ui,node_place_search,node_route_hook toneBlue
class node_core,node_mapbox,node_rank,node_fresh_routes,node_simulation,node_live,node_guidance toneAmber
class node_mapview,node_drive_features,node_signal_data,node_osm,node_signal_store toneMint
class node_device_api,node_native toneRose
class node_kit_stage,node_kit_actions,node_kit_cursor,node_kit_measure,node_driver toneIndigo
```

## Components

### Trip planning

- [App orchestration](https://github.com/akashdesai93/routeiq/blob/main/src/App.tsx): `src/App.tsx`
- [Trip controls](https://github.com/akashdesai93/routeiq/blob/main/src/PlanPanel.tsx): `src/PlanPanel.tsx`
- [Place search](https://github.com/akashdesai93/routeiq/blob/main/src/usePlaceSearch.ts): `src/usePlaceSearch.ts`
- [Route planning](https://github.com/akashdesai93/routeiq/blob/main/src/useRoutes.ts): `src/useRoutes.ts`

### Routing and driving

- [Route domain core](https://github.com/akashdesai93/routeiq/blob/main/src/core/geo.ts): `src/core/geo.ts`
- [Mapbox directions](https://github.com/akashdesai93/routeiq/blob/main/src/providers/mapbox/client.ts): `src/providers/mapbox/client.ts`
- [Route ranking](https://github.com/akashdesai93/routeiq/blob/main/src/core/rank.ts): `src/core/rank.ts`
- [Fresh route checks](https://github.com/akashdesai93/routeiq/blob/main/src/drive/freshRoutes.ts): `src/drive/freshRoutes.ts`
- [Drive simulation](https://github.com/akashdesai93/routeiq/blob/main/src/drive/simulation.ts): `src/drive/simulation.ts`
- [Live guidance](https://github.com/akashdesai93/routeiq/blob/main/src/core/live.ts): `src/core/live.ts`
- [Turn guidance](https://github.com/akashdesai93/routeiq/blob/main/src/core/guidance.ts): `src/core/guidance.ts`

### Map and signal data

- [Route map](https://github.com/akashdesai93/routeiq/blob/main/src/map/MapView.tsx): `src/map/MapView.tsx`
- [Drive map features](https://github.com/akashdesai93/routeiq/blob/main/src/map/driveFeatures.ts): `src/map/driveFeatures.ts`
- [Signal data loader](https://github.com/akashdesai93/routeiq/blob/main/src/signalData.ts): `src/signalData.ts`
- [Overpass signals](https://github.com/akashdesai93/routeiq/blob/main/src/providers/osm/client.ts): `src/providers/osm/client.ts`
- [Signal tile cache](https://github.com/akashdesai93/routeiq/blob/main/src/storage/kv.ts): `src/storage/kv.ts`

### Device services

- [Device location](https://github.com/akashdesai93/routeiq/blob/main/src/device/geolocation.ts): `src/device/geolocation.ts`
- [Native shell bridge](https://github.com/akashdesai93/routeiq/blob/main/src/device/native/index.ts): `src/device/native/index.ts`

### Design kit

- [Stage runtime](https://github.com/akashdesai93/routeiq/blob/main/design/kit/stage.tsx): `design/kit/stage.tsx`
- [Action scripts](https://github.com/akashdesai93/routeiq/blob/main/design/kit/act.ts): `design/kit/act.ts`
- [Cursor behavior](https://github.com/akashdesai93/routeiq/blob/main/design/kit/cursor.tsx): `design/kit/cursor.tsx`
- [Geometry utilities](https://github.com/akashdesai93/routeiq/blob/main/design/kit/measure.ts): `design/kit/measure.ts`

### Other components

- **Driver**

## Connections

- Driver → App orchestration: plans and drives (evidence: `README.md`)
- App orchestration → Trip controls: presents trip controls (evidence: `src/App.tsx`)
- Trip controls → Place search: searches places
- Trip controls → Route planning: requests routes
- Route planning → Mapbox directions: fetches directions (evidence: `src/useRoutes.ts`)
- Route planning → Signal data loader: loads signal counts (evidence: `src/useRoutes.ts`)
- Route planning → Route domain core: ranks routes (evidence: `src/useRoutes.ts`)
- Mapbox directions → Route domain core: parses directions (evidence: `src/providers/mapbox/client.ts`)
- App orchestration → Route map: shows trip map (evidence: `src/App.tsx`)
- Route map → Drive map features: builds drive features (evidence: `src/map/MapView.tsx`)
- Signal data loader → Overpass signals: requests missing tiles (evidence: `src/signalData.ts`)
- Signal data loader → Signal tile cache: caches tiles (evidence: `src/signalData.ts`)
- Overpass signals → Signal data loader: returns signal tiles (evidence: `src/providers/osm/client.ts`)
- Route map → Driver: displays routes
- Fresh route checks → Mapbox directions: checks fresh routes (evidence: `src/drive/freshRoutes.ts`)
- Fresh route checks → Signal data loader: counts fresh signals (evidence: `src/drive/freshRoutes.ts`)
- Fresh route checks → Drive simulation: applies simulated delay (evidence: `src/drive/freshRoutes.ts`)
- App orchestration → Live guidance: starts live drive
- Live guidance → Turn guidance: produces turn prompts
- App orchestration → Native shell bridge: configures shell services (evidence: `src/App.tsx`)
- Native shell bridge → Device location: uses device location (evidence: `src/device/native/index.ts`)
- Stage runtime → Action scripts: plays scripts (evidence: `design/kit/act.ts`)
- Stage runtime → Cursor behavior: uses cursor behavior
- Stage runtime → Geometry utilities: uses geometry