# Valhalla Pure Rust Routing Engine (`valhalla-rs`)
## Native Makepad Integration Guide & Architecture Overview

`valhalla-rs` is a Pure Rust port and architectural rewrite of the **Valhalla Routing Engine**, designed specifically for cross-platform **Makepad UI Framework** applications (`nigig-rider`, `nigig-delivery`, `nigig-tow`, `nigig-mobility`).

---

## 1. Crate Architecture

The suite is organized into modular pure Rust crates under `crates/apps/valhalla/`:

```text
crates/apps/valhalla/
├── valhalla              # Top-level unified facade crate
├── valhalla-core         # Midgard geometry & Baldr GraphTile binary bitfield reader
├── valhalla-cost         # Auto, Bicycle, Pedestrian, Truck, & Transit costing profiles
├── valhalla-path         # DoubleBucketQueue, A*, Bidi A*, Matrix, & MultiModal A*
├── valhalla-search       # Location snapping & candidate edge locator (Loki)
├── valhalla-match        # HMM Viterbi trajectory map matcher (Meili)
├── valhalla-narrative    # Maneuver builder, NarrativeDictionary, & VerbalTextFormatter
├── valhalla-service      # Tyr ValhallaActor service API
├── valhalla-makepad      # Makepad UI overlay & DriverGuidanceController
├── valhalla-builder      # OSM PBF tag parser, PbfReader, TileGenerator & shortcuts
└── valhalla-diff         # Golden differential parity test harness
```

---

## 2. Quickstart & Integration Usage

### 2.1 Basic Route Query (`ValhallaActor`)

```rust
use valhalla::{ValhallaActor, PointLL};

// Initialize actor with loaded GraphTiles
let actor = ValhallaActor::new(tile_buffers);

let origin = PointLL::new(36.8219, -1.2921);      // Nairobi CBD
let destination = PointLL::new(36.8050, -1.2650); // Westlands

// Calculate route response
let response = actor.route(origin, destination, "auto");

if response.status == 200 {
    println!("Total Distance: {} meters", response.directions.total_distance_meters);
    println!("Total Time: {} seconds", response.directions.total_time_secs);

    for maneuver in &response.directions.maneuvers {
        println!("Instruction: {}", maneuver.instruction);
    }
}
```

### 2.2 Live Driver Navigation & Off-Route Auto-Rerouting (`DriverGuidanceController`)

```rust
use valhalla::{DriverGuidanceController, ValhallaActor, PointLL, GuidanceEvent};

let actor = ValhallaActor::new(tile_buffers);
let mut controller = DriverGuidanceController::new(actor);

// Set calculated route
controller.set_active_route(route_response);

// On GPS location update from robius-location
let gps_coord = PointLL::new(36.8220, -1.2915);
let events = controller.on_location_update(gps_coord, "auto");

for event in events {
    match event {
        GuidanceEvent::UpdatedHud(hud_data) => {
            println!("HUD Step: {}", hud_data.current_instruction);
            println!("Distance to turn: {}m", hud_data.distance_to_next_maneuver_meters);
        }
        GuidanceEvent::Rerouted(new_route) => {
            println!("Off-route detected! Auto-rerouted along new path.");
        }
        GuidanceEvent::ArrivedAtDestination => {
            println!("Arrived at destination!");
        }
    }
}

// Generate GPU stroke overlay for nigig-map
let overlay = controller.get_route_overlay();
```

---

## 3. Testing & CI Verification

Run the isolated test harness across all 10 Valhalla subcrates:

```bash
TEST_TARGET=valhalla ./tools/test-rust-clean.sh
```

All 45 unit and integration parity tests must pass cleanly under `rustfmt` and `clippy`.