project-yukart/docs/REPOS.md

type

type
reference

Repositories

Splitting rule

• project-yukart — overview, roadmap, cross-cutting design. No code, ever.
• orin-nano-env-setup — the host: kernel modules, drivers, OS packages, device permissions, systemd plumbing. Anything that must be true before an application starts.
• One repo per application or application cluster. A cluster is a set of services that are developed, versioned and deployed together.
• Helper/deployment repos stand alone when they are reusable outside Yukart.

Anything cross-repo — topic names, payload schemas, the DBC — belongs in the contracts repo, not copied into each consumer.

Current

Repository	Role
project-yukart	Hub: overview, roadmap, architecture
orin-nano-env-setup	Jetson host bring-up
app-flutter	Flutter display client
svc-gw	Telemetry gateway — aggregation and the HTTP surface
svc-nav	Navigation service — routing and guidance
tool-mapmint	Map artifact minting, workstation-side
tool-mock	Mocks and fixtures — a fake car on a workstation

Planned

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
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

Create these lazily — when there is something to put in them, not before.

Naming

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 generic and outside the org — e.g. an ESP32 project skeleton with the toolchain, flashing scripts and CI already wired up.

Gitea template repositories

Gitea supports these: repo Settings → Repository → Template, after which the repo offers "Use this template" to create new repos from it.

Use a template repo for scaffolding — a new ESP32 or Arduino project that should start with the toolchain, directory layout and flashing scripts in place.

Do not use one for code you intend to keep updating in one place. Template instantiation is a fork-at-create: the copy has no link back, so improvements to the template never reach repos already created from it. For genuinely shared code, use a git submodule or publish a package instead.

Rule of thumb: template for the starting shape, submodule/package for living code.

Linking convention

Cross-repo links use the gitea:owner/repo scheme, as established in the hub README — e.g. [Environment setup](gitea:yukart/orin-nano-env-setup).

Per-repo document layout

Following the convention already set by orin-nano-env-setup:

README.md            minimal portal, points everywhere else
docs/
  GUIDELINES.md      implementation practice for this repo
  BOM.md             hardware, where the repo owns hardware
  impl/
    plans/           what is intended
    reports/         what actually happened, and why

The impl/plans ÷ impl/reports split is worth keeping: plans go stale, reports do not. A report like PCAN-SETUP.md stays valuable precisely because it records the investigation and the dead ends, not just the final commands.

Scaffolding conventions

Component repos are scaffolded by hand. A template repo is for carrying a real toolchain, which is the ESP32 case above.

Every component repo carries:

README.md                 the shared blurb, "What this repo is about", then
                          links to guidelines and impl/
docs/GUIDELINES.md        numbered sections, ends "## N. To be added"
docs/impl/plans/          at least INITIAL.md
docs/impl/reports/
docs/BOM.md               only where the repo owns hardware

Languages

Where	Language	Why it is there
svc-* — on the Orin	Rust	No GC, low resident memory on a shared 8 GB pool, and fast start for the tier-1 capture services
tool-* — off-car	Python	Batch work where development speed is the only constraint that binds
app-flutter	Dart	Flutter

Python floors at 3.10, the Orin's version, for anything that might run there. The workstation has 3.14; do not rely on it.

Rust binaries are built for aarch64-unknown-linux-gnu. Cargo.lock and pubspec.lock are committed — these are applications, not libraries.

Writing style

Documents describe what is and what will be. They are not changelogs — git holds the sequence.

Instead of	Write
"X was dropped because Y"	what the design is
"this was a risk, now resolved"	what runs, and the measurements
"the earlier decision assumed Z"	the current constraint
"X was rejected in favour of Y"	Y, stated as the rule

⚠ A sentence justifying a current state by a current reason becomes false when the reason changes, and nothing announces it — it stays, confident and well-written, and reads as fact.

Two things survive the cut, because they stay true when their subject is gone:

• A mechanism that can bite again. Not "we picked the wrong extract once", but "driving side is a country-level property, so a clipped extract routes mirrored".
• A condition that would change the decision, stated generally — "a permanently installed, car-powered panel" rather than a story about a panel that was considered.

Reports under impl/reports/ are the exception and the place for all of it: the investigation, the dead ends, what was measured and found wrong.

Front matter

Every markdown document carries front matter, with no exceptions for the hub or for any particular repo. The type discriminates:

type	Applies to	Extra fields
reference	READMEs, OVERVIEW, ARCHITECTURE, BOM — things that describe what is	—
guidelines	GUIDELINES.md	—
plan	anything under impl/plans/, plus ROADMAP.md	status, updated
report	anything under impl/reports/	date

status is one of active, superseded or done.

status and updated make a plan's staleness visible — plans go stale and reports do not, and without them a plan from months ago reads identically to one written this morning. date on a report records the moment it describes.

Naming

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 generic and outside the org — e.g. an ESP32 project skeleton with the toolchain, flashing scripts and CI already wired up.

Gitea template repositories

Gitea supports these: repo Settings → Repository → Template, after which the repo offers "Use this template" to create new repos from it.

Use a template repo for scaffolding — a new ESP32 or Arduino project that should start with the toolchain, directory layout and flashing scripts in place.

Do not use one for code you intend to keep updating in one place. Template instantiation is a fork-at-create: the copy has no link back, so improvements to the template never reach repos already created from it. For genuinely shared code, use a git submodule or publish a package instead.

Rule of thumb: template for the starting shape, submodule/package for living code.

Linking convention

Cross-repo links use the gitea:owner/repo scheme, as established in the hub README — e.g. [Environment setup](gitea:yukart/orin-nano-env-setup).

Per-repo document layout

Following the convention already set by orin-nano-env-setup:

README.md            minimal portal, points everywhere else
docs/
  GUIDELINES.md      implementation practice for this repo
  BOM.md             hardware, where the repo owns hardware
  impl/
    plans/           what is intended
    reports/         what actually happened, and why

The impl/plans ÷ impl/reports split is worth keeping: plans go stale, reports do not. A report like PCAN-SETUP.md stays valuable precisely because it records the investigation and the dead ends, not just the final commands.

Scaffolding conventions

No template repository for this. Template instantiation is fork-at-create, so it could not reach the repos that already exist, and the scaffolding is three markdown files — lighter than the machinery to manage it. A template earns its place where there is a real toolchain to carry, which is the ESP32 case above.

What every component repo has instead:

README.md                 frontmatter, the shared blurb, "What this repo is
                          about", then links to guidelines and impl/
docs/GUIDELINES.md        frontmatter, numbered sections, ends "## N. To be added"
docs/impl/plans/          at least INITIAL.md
docs/impl/reports/
docs/BOM.md               only where the repo owns hardware

Frontmatter follows the document's nature, not its location: living documents carry type: default; historical records do not. So README, GUIDELINES, BOM and plans have it, and reports do not. The hub carries none at all, being the portal rather than a component.