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 |