nigig-org/REVIEWS/VALHALLA_RIDER_MAP_INTEGRATION_PLAN.md

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).