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](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 |
|---|---|---|
| `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 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.