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

type, status, updated

type	status	updated
plan	active	2026-10-12

Initial plan

Scope

Aggregation and the HTTP surface. Not a telemetry relay: over USB the tablet has an IP link via RNDIS, and a client that can subscribe to the broker does so directly.

Job	Why it needs a gateway
Aggregation	Raw CAN at 500 kbps must never reach a display; something has to downsample
Nav HTTP proxy	Route requests are request/response and fit MQTT badly
Static assets	Serving the PMTiles basemap to the display
Non-IP transports	BT SPP and plain serial for ESP32 clients have no broker access

Order

0. Boundary v0 — in place: WebSocket on :7700, hello, heartbeats both ways, mark forwarded to the recorder's control socket, mock state behind --mock. Protocol in contracts docs/BOUNDARY.md. Bus input — in place (2026-10-12): subscribes to yukart/vehicle/+, yukart/host/+, yukart/gnss/+ and yukart/imu/+, keeps the newest envelope per signal, marks stale after 5 s or when known only from a retained copy. Bus or mock, never both.
1. Static file serving for the basemap — smallest useful thing, unblocks the map.
2. Nav HTTP proxy to svc-nav.
3. Aggregation and rate limiting, once there is real CAN traffic to aggregate.
4. Serial bridge, when an ESP32 client exists.

Two roles in one process

This is both the local aggregation hub and the app gateway. That is allowed because the hub holds no durable state — it is rebuilt from retained topics on restart — but it holds only while these rules do:

• Steady state is reached with zero clients connected. Nothing in aggregation waits on a display.
• The boundary is drop-only: bounded per-client queues, drop oldest, never block. A tablet with its screen off must not stall aggregation.
• Backpressure never propagates inward. Drop at the boundary; never slow the bus subscription to match a slow client.
• Per-client state is per-connection and never touches the aggregate.

The point of the rules is that the seam stays visible. If the gateway ever needs to be a separate process, that becomes a refactor rather than a rewrite.

Links

Link	Shape	Initiator
Vehicle and nav state topics	subscribe	—
Command topics	publish	—
Downstream to app	simplex push stream, lossy-tolerant	app connects
Upstream from app	simplex request/response, acknowledged	app
Route requests onward	request/response, HTTP	this service

Self-mocking

The input side sits behind an interface. The real implementation subscribes to the bus; the mock synthesises vehicle state. Everything from aggregation outward — the boundary protocol, serialisation, per-client queues, reconnection — is identical in both, so there is no second implementation of the contract to drift.

Same shape as svc-nav's routing provider. A service that can produce its own inputs needs no external stub, and tool-mock deliberately does not contain one.

This is what makes app-flutter developable against a single binary with no broker, no fixtures and no Jetson.

Two rules constrain it:

• The mock must degrade. Missing, stale and implausible signals are the normal state in a car. A mock that always emits a complete, fresh, plausible dataset trains the app to assume something false, and the assumption breaks on the first real drive.
• Mock data must be visibly mock downstream. Synthetic vehicle readings indistinguishable from real ones, on a display in a moving car, is a safety problem rather than a tidiness one. The mode is off by default and flagged in the stream, not merely in a log line at startup.

Boundary v0, as built

• One WebSocket rather than separate push and request/response transports: the two channels keep their different guarantees (drop-oldest down, acked-with-idempotency-key up) on one socket, and the client has one connection to keep alive.
• Threads, not async: a handful of clients at most, and tens of MB matter more here than connection count.
• Peers are filtered by address — loopback, RFC 1918, tailnet 100.64/10. The car unit has an LTE uplink, and a command endpoint must not answer on it.
• Without --mock and with no bus yet, a client sees hello and heartbeats only. That is the honest state of the car today, and still exercises the link, reconnection and marking end to end.
• Signal units are read from contracts' signals.json at build time from a sibling checkout (../contracts). The build fails without it rather than guess.