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

Add navigation, Orin runtime and data flow design; rework repo naming

Browse Source 
Navigation: self-hosted MapLibre + Valhalla + PMTiles, offline-first, with
Japan specifics (left-hand traffic via valhalla_build_admins, data volume,
CJK labels). Map matching pulled forward as Phase 2 ground truth.

Orin runtime: new document covering the 8 GB shared-memory budget,
capture-first startup tiers, failure isolation, storage and the audio graph.

Data flow: direction belongs to topics inside the Orin; the display boundary
is two simplex channels rather than one duplex socket; cloud links are
outbound-initiated only; services mock themselves rather than having separate
stub implementations.

Naming: repositories are <group>-<thing> with no project prefix, so lexical
order matches semantic grouping. Indexes the five new repos.

Decisions 8-19 recorded; 14 (recording retention) left open.

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-04 08:25:26 +09:00
parent 62ac7bd09d
commit 449aa0c99e
5 changed files with 365 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/REPOS.md
+37 -11
View File
@@ -19,31 +19,57 @@ contracts repo, not copied into each consumer.
|---|---|
| [project-yukart](gitea:yukart/project-yukart) | Hub: overview, roadmap, architecture |
| [orin-nano-env-setup](gitea:yukart/orin-nano-env-setup) | Jetson host bring-up |
| [app-flutter](gitea:yukart/app-flutter) | Flutter display client |
| [svc-gw](gitea:yukart/svc-gw) | Telemetry gateway — aggregation and the HTTP surface |
| [svc-nav](gitea:yukart/svc-nav) | Navigation service — routing and guidance |
| [tool-mapmint](gitea:yukart/tool-mapmint) | Map artifact minting, workstation-side |
| [tool-mock](gitea:yukart/tool-mock) | Mocks and fixtures — a fake car on a workstation |
## Planned
| Repository | Role | Why separate |
|---|---|---|
| `yukart-contracts` | Topic namespace, payload schemas, Z27AG DBC | Consumed by every other repo, including non-Jetson clients; must not be duplicated |
| `yukart-core` | Acquisition + processing cluster: `can-bridge`, `obd-poller`, `gnss`, `decoder`, `recorder` | Developed and deployed as one unit on the Orin |
| `yukart-gw` | `telemetry-gw` — serves external display clients | Independent release cycle from acquisition; the network-facing surface |
| `yukart-hud` | Local renderer for the directly-driven screen (Class A) | Its own toolchain and graphics stack |
| `yukart-android` | Android display client (Class B) | Entirely separate toolchain and release process |
| `yukart-esp32-display` | ESP32 RLCD/e-ink display firmware (Class B) | Embedded toolchain, flashed not deployed |
| `yukart-analysis` | Offline session analysis, reverse-engineering notebooks | Runs off-car, no runtime coupling |
| `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 |
| `app-esp32` | ESP32 RLCD/e-ink display firmware (Class B) | Embedded toolchain, flashed not deployed |
| `app-hud` | Local renderer for a directly-driven screen (Class A) | Its own toolchain and graphics stack — **in question**, see the display contract |
| `tool-analysis` | Offline session analysis, reverse-engineering notebooks | Runs off-car, no runtime coupling |
Create these lazily — when there is something to put in them, not before.
## Naming
- `yukart-*` for project-specific repositories.
- **No prefix** for reusable helpers, since the prefix would be a lie the first
time one is used in another project.
Repositories are named `<group>-<thing>`, with **no project prefix**. The `yukart`
Gitea org already namespaces everything, so a `yukart-` prefix would be a constant
occupying the most significant characters of every name — pure noise in a sorted
index, and the reason the earlier scheme scattered.
| Group | Meaning |
|---|---|
| `svc-` | A service running on the Orin |
| `app-` | A display client, running off the Orin |
| `tool-` | Off-car tooling; never deployed to the car |
The goal is that **lexical order equals semantic grouping**: opening the org
listing puts every service together, every client together, every tool together.
The group segment does that work because it is the first thing that varies.
Ungrouped singletons — `contracts` — are fine where a category has exactly one
member and always will.
`project-yukart` and `orin-nano-env-setup` predate this and keep their names
rather than paying a rename for two repos that are stable and easy to find.
### Reusability
Nothing in a name marks a repo as reusable. A component that turns out to be
genuinely reusable outside Yukart **leaves the org** rather than being renamed —
location says it, not spelling.
## Helper and deployment repos
Arduino and ESP32 work implies flashing, build and deployment scaffolding that
is likely to be reused. Keep those unprefixed and generic — e.g. an ESP32
is likely to be reused. Keep those generic and outside the org — e.g. an ESP32
project skeleton with the toolchain, flashing scripts and CI already wired up.
### Gitea template repositories