116 lines
9.2 KiB
Markdown
116 lines
9.2 KiB
Markdown
# Phase 5: Routing + Route Display - Context
|
||
|
||
**Gathered:** 2026-10-24
|
||
**Status:** Ready for planning — **with a roadmap amendment** (SC3 rewording, below)
|
||
|
||
<domain>
|
||
## Phase Boundary
|
||
|
||
The route EXPERIENCE ships end-to-end in fixture world: a `RoutingSource` interface (mirroring `SearchSource`), a fixture backend whose geometries for 10–20 real KL pairs were precomputed at build time, Rams route rendering (orange casing on the grayscale map), up-to-3 alternatives as a bottom card + chips, selection redraw with camera refit, and an honest "router pending" state for arbitrary origins. The `guidance_sessions` envelope is designed as a types-only frozen contract for Phase 6. **No VPS, no Worker route proxy, no third-party routing calls** — the engine itself is deferred to the WASM-router OSS track (client-side routing, backend #2), with Valhalla-on-VPS documented as backend #3.
|
||
|
||
**ROADMAP AMENDMENT (planning must apply):** SC3 is reworded from "routes cleanly through self-hosted Valhalla … behind the Worker proxy" to: "the golden-route corpus (10–20 real KL pairs) routes cleanly through the fixture RoutingSource backend with bundle-size and type gates holding; the RoutingSource interface carries the documented backend ladder (fixtures → client-side WASM router → Valhalla-on-VPS) and the 'router pending' state is deliberate and designed." RTNG-01's "calculated route" is satisfied by fixture calculation; the arbitrary-origin router is a documented deferral, not an omission.
|
||
|
||
</domain>
|
||
|
||
<decisions>
|
||
## Implementation Decisions
|
||
|
||
### Routing infrastructure — THE PIVOT (user decision, supersedes roadmap SC3 v1)
|
||
- **D-01:** **No VPS this phase. No third-party routing API ever at runtime** (origin+destination to a third party is a core-value privacy leak). Routing is a **`RoutingSource` interface** with a backend ladder: **#1 fixtures (this phase) → #2 client-side WASM router (OSS track, deferred) → #3 Valhalla-on-VPS (documented, provision scripts as a documented path, not shipped)**.
|
||
- **D-02:** Backend #1 = **fixture routes for the 10–20 golden KL pairs**, geometries precomputed at BUILD time by a repo script hitting the public OSRM demo server once (build machine, fixed public coordinates — no user data, no runtime dependency), committed as compact encoded polylines. Each pair pins expected distance/duration tolerances.
|
||
- **D-03:** Arbitrary origin/destination combinations return an honest **"router pending"** state — a designed, deliberate Rams surface (UI-SPEC scope), never a blank map, never a fake route, never a silent failure.
|
||
- **D-04:** The **WASM-router track** (client-side routing in the webview — origin+destination never touch a server; static-hosted; fork-perfect) is captured as the post-v1 OSS project that becomes RoutingSource backend #2, exactly parallel to the search backend #2 pattern. The user's static-hosting/fork-model intent is preserved as the architectural direction, not abandoned.
|
||
- **D-05:** The Worker gains **no `/api/route`** this phase. Fixtures ride in the web bundle (gazetteer precedent). The interface stays backend-shaped so a server backend could slot in later without client rework.
|
||
|
||
### guidance_sessions envelope (Phase 6's contract, frozen now)
|
||
- **D-06:** **Types-only contract**: `guidance_sessions` envelope = { id, chat ref, route snapshot (inline), created_at } with a **~2h TTL** — shipped as code types + docs, **no KV namespace, no service, no runtime writes**. Phase 6 builds the service on the frozen shape.
|
||
- **D-07:** Route snapshot lives **inline in the envelope record — one key, one TTL**; nothing outlives 2h, nothing reconstructable after expiry. Consistent with the location-pin TTL precedent (Phase 3). The route model itself carries **step geometry + snapped-progress support fields from day one** (GUID-05/06 upstream obligation).
|
||
|
||
### Route UX surface (UI-SPEC scope; phase-terminal)
|
||
- **D-08:** Alternatives present as a **bottom card + chips**: one card for the selected route (time, distance, one-line difference vs best) with compact alternates as selectable chips — tap → redraw. Map stays dominant.
|
||
- **D-09:** Route line = **signal-orange casing** (dark under-line for grayscale contrast) + orange center line — Phase 1's reserved accent, per the navigate_map_overview mockup. Destination pin keeps venue semantics; origin = subdued ring. Camera **fits route bounds** on draw.
|
||
- **D-10:** **Display-only terminal surface**: selection redraws + camera refits; a restart/search-again affordance returns to the destination state. **No start-guidance button, no turn instructions, no progress UI** — Phase 6. No placeholder-shaped furniture (Phase 3 D-08 law).
|
||
|
||
### Gates replacing SC3's latency/subrequest budgets
|
||
- **D-11:** **Bundle budget**: fixture geometry + route-model code ≤ ~200KB gzipped added to the web bundle, enforced as a BA build-artifact gate. **Type gates**: route model readiness (step geometry + snapped-progress fields) pinned by tests. "Router pending" state covered by UI-SPEC + captures. Latency/subrequest budgets are not applicable to fixture world (documented as such, not faked).
|
||
|
||
### Privacy (carried + made specific)
|
||
- **D-12:** Fixture geometries are public-data routes between public places — no user coordinate ever enters a fixture. The build-time OSRM fetch happens on the maintainer's machine against fixed public points; the script documents this boundary. Runtime: origin stays in memory only (Phase 3 law); no route persists (envelope is types-only this phase).
|
||
|
||
### OpenCode's Discretion
|
||
- Fixture encoding format (encoded-polyline vs simplified GeoJSON) within the ≤200KB budget
|
||
- RoutingSource interface shape (async, backend-tagged results, tolerance metadata)
|
||
- Which Phase 4 corpus destinations become the 10–20 pairs; realistic origins list
|
||
- One-line-difference copy per alternative card (en/ms, clinical tone); "router pending" copy
|
||
- Chip/card visual details within the Rams system (UI-SPEC will bind exact geometry)
|
||
|
||
</decisions>
|
||
|
||
<specifics>
|
||
## Specific Ideas
|
||
|
||
- The route experience should feel like the mockup distilled: the orange line is THE accent on a grayscale world — nothing else competes.
|
||
- "Router pending" copy should be honest and calm: the app knows what routing is, states it isn't wired yet, offers search again. Same clinical register as the denied card.
|
||
- Fixture pairs double as the demo script: the 10–20 pairs are the routes a reviewer walks to see the product work.
|
||
|
||
</specifics>
|
||
|
||
<canonical_refs>
|
||
## Canonical References
|
||
|
||
**Downstream agents MUST read these before planning or implementing.**
|
||
|
||
### Phase scope + decisions
|
||
- `.planning/ROADMAP.md` §Phase 5 — goal, success criteria **+ this file's SC3 amendment (planning applies it)**
|
||
- `.planning/REQUIREMENTS.md` §RTNG-01/02 (+ GUID-05/06 upstream obligations)
|
||
- `.planning/phases/04-destination-search-kl-gazetteer/04-CONTEXT.md` — SearchSource pattern to mirror; backend-ladder pattern; fork-model law (GPL-3.0)
|
||
- `.planning/phases/03-mini-app-shell-geolocation/03-CONTEXT.md` — map boot, marker/follow controller, memory-only law, location-pin TTL precedent
|
||
|
||
### Codebase
|
||
- `web/src/map/` — MapLibre boot (style never re-set — route layers must be addLayer, not style mutation), marker, follow controller
|
||
- `web/src/search/resolve-destination.ts` — the preloaded destination this phase routes TO
|
||
- `search/` — the interface+backend+ladder pattern to mirror
|
||
- `web/scripts/capture.mjs` + mock profiles — the capture harness the route display must extend (`?dest=` profiles exist)
|
||
- `bot/src/i18n/strings.ts` pattern — copy discipline for card/difference strings
|
||
|
||
</canonical_refs>
|
||
|
||
<code_context>
|
||
## Existing Code Insights
|
||
|
||
### Reusable Assets
|
||
- `search/` workspace: interface + ladder + loader + corpus-gate patterns to mirror for `routing/`
|
||
- Phase 4 corpus gate (D-13/D-14) — the fixture-pair tolerance gate follows its shape
|
||
- Mock harness profiles (`?dest=`) — route-state capture profiles extend these
|
||
- BA build-artifact gates — the bundle-budget gate joins them
|
||
|
||
### Established Patterns
|
||
- npm workspaces + delegate scripts; TDD RED→GREEN; hand-rolled runners
|
||
- Interface + documented backend ladder (SearchSource → RoutingSource)
|
||
- Types-only frozen contracts (session envelope) with TTL-only storage law
|
||
- UI-SPEC gate applies this phase (UI hint: yes) — planning routes through it
|
||
|
||
### Integration Points
|
||
- Destination resolver → route destination input (Phase 4 hands off where Phase 5 begins)
|
||
- Route model step geometry + snapped-progress fields → Phase 6 guidance consumes
|
||
- `guidance_sessions` envelope types → Phase 6 bot service implements
|
||
|
||
</code_context>
|
||
|
||
<deferred>
|
||
## Deferred Ideas
|
||
|
||
- **WASM-router OSS project** — client-side routing in the webview (RoutingSource backend #2); static-hosted, privacy-maximal, fork-perfect; its own post-v1 project
|
||
- **Valhalla-on-VPS** — RoutingSource backend #3; docker-compose + Caddy + provision scripts as a documented path (Oracle Always Free candidate; full-MY extract chosen if provisioned)
|
||
- **Worker `/api/route` proxy** — only meaningful with a server backend
|
||
- **Real routing for arbitrary origins** — arrives with backend #2/#3; the "router pending" state is the honest interim
|
||
- Turn instructions/progress UI — Phase 6 (GUID-*)
|
||
- Toll-avoidance / costing knobs — v1.x
|
||
|
||
</deferred>
|
||
|
||
---
|
||
|
||
*Phase: 05-routing-route-display*
|
||
*Context gathered: 2026-10-24*
|