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

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. Template instantiation is fork-at-create, so it could not reach repos that already exist, and the scaffolding is a handful of 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.

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

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.

The extra fields exist for one reason. This document already observes that plans go stale and reports do not — but nothing made staleness visible, so a plan written months ago looked identical to one written this morning. status and updated fix that; date on a report records the moment it describes, which is the whole value of a report.

A type with one possible value would be decoration. This one has four and they are worth grepping for.

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.