Scaffold repo: docs layout, guidelines and initial plan

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ
2026-09-03 18:48:32 +09:00
commit b85a53e779
4 changed files with 65 additions and 0 deletions
@@ -0,0 +1,16 @@
+---
+type: default
+---
+# Gateway guidelines
+
+## 1. Read-only with respect to acquisition
+- The gateway subscribes. It never opens a CAN socket, TX-capable or otherwise.  
+- `obd-poller` is the single writer on the bus. Nothing here changes that.
+
+## 2. Aggregate, do not relay
+- A 500 kbps CAN bus produces far more traffic than a display can use or a USB
+  link should carry. Downsample and summarise here.  
+- If the gateway is only forwarding a topic unchanged, that client should have
+  subscribed to the broker directly instead.
+
+## 3. To be added
@@ -0,0 +1,30 @@
+---
+type: default
+---
+# Initial plan
+
+## The scope question, first
+
+This started as "aggregator and pusher to the tablet over USB". The pushing part
+may not need to exist: over USB the tablet has an IP link via RNDIS, and the
+architecture already says Class B devices reaching the bus over IP connect to the
+broker directly. A Flutter MQTT client can talk to mosquitto with no hop in between.
+
+What does not go away:
+
+| 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 |
+
+So: build the aggregation and the HTTP surface. Do not build a telemetry relay for
+clients that can already subscribe for themselves.
+
+## Order
+
+1. Static file serving for the basemap — smallest useful thing, unblocks the map.
+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.