# Valhalla Pure Rust Engine, `nigig-map`, and `nigig-rider` Integration Plan
## End-to-End Architectural Specification & Implementation Roadmap

**Date:** July 28, 2026  
**Target Application:** `nigig-rider` (Riding App) & `nigig-map` (Map Renderer)  
**Routing Engine:** `valhalla` (`crates/apps/valhalla/*`)  
**GPS Tracking:** `robius-location`

---

## 1. Executive Summary & Integration Architecture

With the completion of the Pure Rust **Valhalla Routing Engine (`valhalla-rs`)**, this plan specifies the exact technical architecture to connect the routing engine with the **Makepad Map Renderer (`nigig-map`)** and the **Rider Riding Application (`nigig-rider`)**.

```
  ┌────────────────────────────────────────────────────────────────────────┐
  │                           nigig-rider App                              │
  │                                                                        │
  │  1. `RiderBookPage` (Search / Pin Drop)                                │
  │  2. `RiderTrackPage` (Live Navigation HUD & Driver Tracking)           │
  └───────────────────┬────────────────────────────────┬───────────────────┘
                      │                                │
                      ▼                                ▼
       ┌──────────────────────────────┐  ┌──────────────────────────────┐
       │   valhalla::ValhallaActor    │  │ valhalla::DriverGuidance     │
       │   (A* Route & Matrix Engine) │  │ Controller (HMM GPS Snapper) │
       └──────────────┬───────────────┘  └──────────────┬───────────────┘
                      │                                │
                      └────────────────┬───────────────┘
                                       │
                                       ▼
                      ┌─────────────────────────────────┐
                      │    nigig-map Map Renderer       │
                      │                                 │
                      │  • RouteRenderPass (StrokePass) │
                      │  • Waypoint Marker Pass         │
                      └─────────────────────────────────┘
```

---

## 2. Key Technical Integration Points

### 2.1 Route Overlay Pass in `nigig-map` (`RouteRenderPass`)
`nigig-map` uses a modular `RenderGraph` pipeline with explicit pass ordering:
- `PassType::Background` ($z=0$)
- `PassType::Fill` ($z=100$)
- `PassType::Stroke` ($z=200$)
- `PassType::Poi` ($z=300$)
- `PassType::Label` ($z=400$)
- `PassType::Selection` ($z=500$)

**Action:** Add a custom `RouteRenderPass` ($z=250$, between road stroke and POI) implementing `RenderPass` in `crates/apps/map/src/render_graph.rs`:
- Reads route shape points (`Vec<PointLL>`) from `valhalla::ui::RouteOverlay`.
- Converts geographic coordinates (`PointLL`) to Mercator screen space using `lon_lat_to_normalized(lng, lat) * world_size + map_offset`.
- Tessellates route polylines into GPU stroke vertices with navigation-blue casing (`#3b82f6`) and 6px stroke width.

### 2.2 `RiderBookPage` Integration (`crates/apps/nigig-rider/src/rider_frame/pages/book.rs`)
- On destination search or location row tap:
  1. Retrieve origin coordinate (current GPS position or map center: $36.8219, -1.2921$).
  2. Issue route request: `actor.route(origin, destination, "auto")`.
  3. Extract `RouteResponse` polyline shape and pass to `NigigMapView::set_route_overlay()`.
  4. Display ETA summary card (total distance in km, travel duration in minutes).

### 2.3 `RiderTrackPage` Integration (`crates/apps/nigig-rider/src/rider_frame/pages/track.rs`)
- On live GPS updates from `robius-location`:
  1. Feed location to `DriverGuidanceController::on_location_update(coord, "auto")`.
  2. Update `NavigationHudData` UI card (current turn maneuver instruction, distance to turn, next turn arrow).
  3. On `GuidanceEvent::Rerouted(new_route)` ($>25\text{m}$ off-route threshold): update map route overlay line and recalculate ETA automatically.

---

## 3. Step-by-Step Execution Roadmap

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │                      5-STEP IMPLEMENTATION ROADMAP                      │
 │                                                                        │
 │  STEP 1: Add `RouteRenderPass` to `nigig-map` RenderGraph              │
 │  STEP 2: Add `set_route_overlay()` API to `NigigMapView`              │
 │  STEP 3: Wire `ValhallaActor` into `RiderBookPage` (`book.rs`)          │
 │  STEP 4: Wire Guidance HUD & `robius-location` into `track.rs`         │
 │  STEP 5: Validate via `tools/test-rust-clean.sh` & Push to Gitdab      │
 └────────────────────────────────────────────────────────────────────────┘
```

### Step 1: Add `RouteRenderPass` to `nigig-map`
- **File:** `crates/apps/map/src/render_graph.rs`
- Add `PassType::Route` ($z=250$) and implement `RenderPass` for `RoutePass` rendering polyline strokes over road networks.

### Step 2: Add `set_route_overlay()` API to `NigigMapView`
- **File:** `crates/apps/map/src/view.rs`
- Add `pub fn set_route_overlay(&mut self, cx: &mut Cx, overlay: Option<valhalla::ui::RouteOverlay>)` to update active route overlays and trigger `redraw(cx)`.

### Step 3: Wire `ValhallaActor` into `RiderBookPage`
- **File:** `crates/apps/nigig-rider/src/rider_frame/pages/book.rs`
- Instantiate `ValhallaActor` on page load, attach destination tap handler, and render ETA card on route completion.

### Step 4: Wire Guidance HUD into `RiderTrackPage`
- **File:** `crates/apps/nigig-rider/src/rider_frame/pages/track.rs`
- Instantiate `DriverGuidanceController`, bind location stream, and update navigation HUD cards.

### Step 5: Verification & Testing
- Test using `TEST_TARGET=valhalla` and `cargo check -p nigig-rider` to ensure clean compilation.

---

## 4. Expected User Experience Outcome

When complete:
1. **Interactive Route Planning:** Tapping any location in `nigig-rider` instantly renders a smooth blue route overlay line along the road network on `NigigMapView`.
2. **Turn-by-Turn Guidance HUD:** Displays upcoming maneuvers (*"Turn right onto Uhuru Highway in 200m"*).
3. **Live GPS Tracking & Auto-Rerouting:** Snaps driver location to road network and automatically recalculates routes if the driver takes a wrong turn ($>25\text{m}$ deviation).