From d5c4da8e387322fc062002e1db230acd3f7c0cd0 Mon Sep 17 00:00:00 2001 From: Mikkeli Date: Thu, 3 Sep 2026 20:28:32 +0900 Subject: [PATCH] Record link shapes and boundary semantics in initial plan Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ --- docs/impl/plans/INITIAL.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/impl/plans/INITIAL.md b/docs/impl/plans/INITIAL.md index 64aa5cc..fa68fed 100644 --- a/docs/impl/plans/INITIAL.md +++ b/docs/impl/plans/INITIAL.md @@ -28,3 +28,30 @@ clients that can already subscribe for themselves. 2. Nav HTTP proxy to [svc-nav](gitea:yukart/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 |