svc-nav/docs/impl/plans/INITIAL.md

type

type
default

Initial plan

Scope

Turn a GNSS fix plus a destination into guidance on the bus. Nothing about rendering — that belongs to the display client.

Order

1. Confirm Valhalla builds and runs on the Jetson (arm64). This is the one real integration risk in the whole navigation workstream — upstream's arm64 container story is unsettled. Do it before anything else.
2. Stand up Valhalla against artifacts from tool-mapmint, serving HTTP locally.
3. Define the routing provider interface, with Valhalla as the first implementation.
4. Bridge: subscribe to yukart/gnss/fix, publish yukart/nav/guidance.
5. Meili map matching over recorded sessions — see below.

Why map matching comes early

Meili's trace_attributes snaps a recorded GNSS trace onto OSM and returns road attribution along it: speed limit, road class, geometry. That is ground truth for validating reverse-engineered CAN signals, which is otherwise guesswork. It is worth having before any navigation UI exists.

Blocked on

Live guidance needs a GNSS fix, which needs gpsd, which needs the SIM7600 brought up in orin-nano-env-setup. Everything else here can be built and validated against a replayed trace.

Links

Link	Shape	Initiator
yukart/gnss/fix	subscribe	—
yukart/nav/{guidance,route}	publish, retained	—
Route requests	request/response, HTTP	svc-gw
Cloud routing API, if used	request/response	this service, outbound only

svc-nav never talks to a display. Guidance reaches the app as bus state via svc-gw, and route requests arrive proxied. Nav does not know displays exist.

GNSS is scaffolding for now

The PCBs are not assembled, so there is no real fix yet. Positions come from a replayed trace publishing yukart/gnss/fix with the real schema — see the fixtures rule in ARCHITECTURE.md. Everything downstream is then identical when the hardware lands.