project-yukart/docs/REPOS.md

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

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

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.

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