Dual Routing Engine

"/home/yossef/notes/git/projects/maplibra/decisions/Dual Routing Engine.md"

path: maplibra/decisions/Dual Routing Engine.md

- **fileName**: Dual Routing Engine
- **Created on**: 2026-06-16 00:48:42

Purpose: Why the app supports both a JS routing engine and an optional WASM kernel.

Decision

Maintain two routing engines with identical logic: a pure JS engine for compatibility and a WASM kernel for performance.

WASM is not universally supported — some browsers or environments disable WebAssembly
WASM compilation can fail — large WASM binaries may timeout or OOM on low-end devices
JS is the reliable fallback — always works, always available
Parity verification — having both engines allows comparing results to detect bugs
Performance gains — WASM can be 2-5x faster for A* on large graphs

JS Engine (src/pathfinding/route-compute.js) — pure JavaScript A* with MinHeap
WASM Engine (native/routing/*.c compiled to WASM) — C implementation of the same algorithms
Bridge (src/pathfinding/wasm/route-kernel-bridge.js) — JS-to-WASM communication layer
Worker (src/workers/path-worker.js) — runs pathfinding in a Web Worker to avoid blocking the main thread

Default: routing.engine=js (safe, compatible)
Opt-in: routing.engine=wasm (faster, but may fallback)
Fallback reasons: worker-construction-failed, worker-error, wasm-init-failed, wasm-init-timeout
Fallback is automatic and silent — the user never sees an error

routing.wasmParity=1 enables result comparison between JS and WASM
compareRouteResults() in src/pathfinding/binary-graph-parity.js compares outputs
Mismatches are logged and sent to telemetry

Pro: Compatibility, reliability, performance option, bug detection via parity
Con: Double maintenance burden, larger bundle (WASM binary), more complex testing
Mitigation: WASM is lazy-loaded; the JS engine is always present in the main bundle

Phase 5+ of the product hardening effort. The WASM kernel was added to improve routing performance on large campuses.