yukart/project-yukart
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Index contracts; record the envelope's two clocks and single-source rule

Browse Source 
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ
This commit is contained in:
Mikkeli Matlock
2026-09-05 12:54:28 +09:00
parent b9d138652e
commit e5adcf1afe
2 changed files with 12 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+11 -3
View File
@@ -78,9 +78,15 @@ yukart/nav/guidance next manoeuvre, distance, street name, retained
yukart/nav/route active route geometry, retained yukart/nav/route active route geometry, retained
``` ```
Payloads: JSON for low-rate signals (readable, debuggable); compact binary or Payloads: a self-describing JSON envelope for decoded signals; compact binary for
CBOR for `can/raw`, since a 500 kbps bus produces far more traffic than JSON `can/raw`, since a 500 kbps bus produces far more traffic than JSON should carry.
should carry.
Every envelope carries **two clocks**. `monotonic` is authoritative for ordering
and intervals; `timestamp` is the absolute reference and may step, since the car
boots without network and NTP corrects the clock once LTE connects mid-drive.
Topic names, payload schemas and the signal registry live in
[contracts](gitea:yukart/contracts).
Topic names and payload schemas are a **contract shared across repos** — Android Topic names and payload schemas are a **contract shared across repos** — Android
and ESP32 clients depend on them — so they are versioned in their own repo and ESP32 clients depend on them — so they are versioned in their own repo
@@ -308,6 +314,8 @@ rewriting the document.
| 3 | Listen-only sniffing + active OBD-II, single writer | Accepted | 2026-08-14 | | 3 | Listen-only sniffing + active OBD-II, single writer | Accepted | 2026-08-14 |
| 4 | MQTT as the bus | **Proposed** | 2026-08-14 | | 4 | MQTT as the bus | **Proposed** | 2026-08-14 |
| 5 | Rust for on-Orin services, Python for off-car tooling, Dart for the display client | Accepted | 2026-09-04 | | 5 | Rust for on-Orin services, Python for off-car tooling, Dart for the display client | Accepted | 2026-09-04 |
| 21 | Two clocks per envelope; `monotonic` orders, `timestamp` references | Accepted | 2026-09-05 |
| 22 | `signals.json` is the single source for signal name and unit; both are derived, never authored twice | Accepted | 2026-09-05 |
| 6 | Local logging first; off-board LTE telemetry deferred | Accepted | 2026-08-14 | | 6 | Local logging first; off-board LTE telemetry deferred | Accepted | 2026-08-14 |
| 7 | Camera/AI inference is a later, separate task | Accepted | 2026-08-14 | | 7 | Camera/AI inference is a later, separate task | Accepted | 2026-08-14 |
| 8 | Self-hosted offline navigation (MapLibre GL + Valhalla + PMTiles) over a cloud maps SDK | Accepted | 2026-09-03 | | 8 | Self-hosted offline navigation (MapLibre GL + Valhalla + PMTiles) over a cloud maps SDK | Accepted | 2026-09-03 |
docs/REPOS.md
+1 -1
View File
@@ -23,6 +23,7 @@ contracts repo, not copied into each consumer.
| [project-yukart](gitea:yukart/project-yukart) | Hub: overview, roadmap, architecture | | [project-yukart](gitea:yukart/project-yukart) | Hub: overview, roadmap, architecture |
| [orin-nano-env-setup](gitea:yukart/orin-nano-env-setup) | Jetson host bring-up | | [orin-nano-env-setup](gitea:yukart/orin-nano-env-setup) | Jetson host bring-up |
| [app-flutter](gitea:yukart/app-flutter) | Flutter display client | | [app-flutter](gitea:yukart/app-flutter) | Flutter display client |
| [contracts](gitea:yukart/contracts) | Topic namespace, payload schemas, signal registry |
| [svc-gw](gitea:yukart/svc-gw) | Telemetry gateway — aggregation and the HTTP surface | | [svc-gw](gitea:yukart/svc-gw) | Telemetry gateway — aggregation and the HTTP surface |
| [svc-nav](gitea:yukart/svc-nav) | Navigation service — routing and guidance | | [svc-nav](gitea:yukart/svc-nav) | Navigation service — routing and guidance |
| [tool-mapmint](gitea:yukart/tool-mapmint) | Map artifact minting, workstation-side | | [tool-mapmint](gitea:yukart/tool-mapmint) | Map artifact minting, workstation-side |
@@ -32,7 +33,6 @@ contracts repo, not copied into each consumer.
| Repository | Role | Why separate | | Repository | Role | Why separate |
|---|---|---| |---|---|---|
| `contracts` | Topic namespace, payload schemas, Z27AG DBC | Consumed by every other repo, including non-Jetson clients; must not be duplicated |
| `svc-core` | Acquisition + processing cluster: `can-bridge`, `obd-poller`, `gnss`, `decoder`, `recorder` | Developed and deployed as one unit on the Orin | | `svc-core` | Acquisition + processing cluster: `can-bridge`, `obd-poller`, `gnss`, `decoder`, `recorder` | Developed and deployed as one unit on the Orin |
| `app-esp32` | ESP32 RLCD/e-ink display firmware (Class B) | Embedded toolchain, flashed not deployed | | `app-esp32` | ESP32 RLCD/e-ink display firmware (Class B) | Embedded toolchain, flashed not deployed |
| `tool-analysis` | Offline session analysis, reverse-engineering notebooks | Runs off-car, no runtime coupling | | `tool-analysis` | Offline session analysis, reverse-engineering notebooks | Runs off-car, no runtime coupling |