<!-- status: unverified -->
<!-- A filled architecture brief for a hypothetical robot, illustrating the
     brief-template. Not from a real trial run — promote to verified once an
     actual app is built from a brief like this. -->

# Architecture Brief — WarehouseBot (diff-drive warehouse navigator)

**Date:** 2026-07-10   **Status:** draft
**Author:** robium-architect subagent

## 1. Requirements

- **Robot type:** differential-drive mobile base (~40 cm footprint), 2D lidar +
  wheel odometry, no manipulator.
- **Task:** navigate autonomously between named pick/drop stations in a
  warehouse, avoiding dynamic obstacles (people, carts).
- **Hardware:** none yet — **sim-first**; a real base is a later phase.
- **Sim vs real:** MVP must run entirely in simulation.
- **GPU:** *assumed none* on the dev machine (laptop). **Assumption** — not
  confirmed; feeds open risks.
- **Local vs remote:** developed on a macOS laptop, so the stack runs in Docker;
  a headless workstation is a possible later target.

## 2. Chosen stack + reasoning

| Layer | Choice | Version | Why (and what was rejected) |
|---|---|---|---|
| Middleware | ROS 2 | Jazzy Jalisco | LTS to 2029; standard nav ecosystem. Lyrical Luth (newer LTS, to 2031) rejected for now — Nav2 has no released binaries for it yet. Kilted rejected — non-LTS, ends 2026. |
| Simulator | Gazebo | Harmonic | Officially paired with Jazzy; no GPU needed. Isaac Sim rejected — GPU-gated, overkill for a lidar nav demo. |
| Navigation | Nav2 | (Jazzy release) | The standard ROS 2 nav stack; costmaps + planners + BT out of the box. Rolling our own rejected — no reason to. |
| Visualization | RViz2 (dev) + Foxglove (remote) | — | RViz2 locally for quick checks; Foxglove for the eventual headless workstation. Rerun rejected — not needed for classical nav. |
| Environment | Docker | Jazzy base image | Dev machine is macOS, which can't run the native ROS 2 + Gazebo desktop cleanly; Docker gives identical local/remote repro. uv rejected — this is a compiled ROS 2 workspace, not pure Python. |

Decisions trace to the architect trees: middleware → ROS 2 (mobile multi-node
system); simulator → Gazebo (no GPU); no training framework (classical nav).

## 3. Module breakdown

- **warehousebot_description** — URDF/xacro of the diff-drive base, lidar + wheel
  frames, meshes. Publishes the robot model. In/out: none / `robot_description`,
  TF.
- **warehousebot_sim** — Gazebo world (warehouse layout, shelves, spawn points)
  and spawn glue. In/out: `robot_description` / simulated `/scan`, `/odom`, TF.
- **warehousebot_navigation** — Nav2 config: costmaps (lidar-based obstacle
  layer + inflation), NavFn/Smac planner, DWB/MPPI controller, behavior tree,
  saved warehouse map. In/out: `/scan`,`/odom`,`/map`,goal / `/cmd_vel`.
- **warehousebot_bringup** — top-level launch (sim + nav + viz) and params.
  In/out: launch args / the running system.

## 4. Comms plan

Standard ROS 2 topics, single robot, all in-process for the MVP.

| Topic | Type | Rate | Producer → Consumer |
|---|---|---|---|
| `/scan` | `sensor_msgs/LaserScan` | ~10 Hz | Gazebo lidar → Nav2 costmap |
| `/odom` | `nav_msgs/Odometry` | ~30 Hz | Gazebo diff-drive → Nav2, TF |
| `/cmd_vel` | `geometry_msgs/Twist` | ~20 Hz | Nav2 controller → base |
| `/map` | `nav_msgs/OccupancyGrid` | latched | map_server → Nav2 |
| goal | `nav2` action (`NavigateToPose`) | on demand | app → Nav2 BT |

No cross-host transport needed for the MVP. If the fleet grows to multiple
robots later, revisit with the `integration` skill (namespacing, DDS discovery).

## 5. Environment strategy

Docker, single `Dockerfile` on a ROS 2 Jazzy base plus Gazebo Harmonic and Nav2
from ROS vendor packages; a `compose.yaml` running sim + nav + viz. macOS dev
uses an X/Wayland forward or Foxglove for viewing. The same image runs on the
headless workstation later — identical repro is the reason Docker was chosen
over a native workspace. No GPU passthrough (none required). Detail: route to
the `environments` skill.

## 6. Data plan

No learned components → no datasets. Data artifacts are: the saved warehouse
occupancy `map` (built once via SLAM in sim, then reused), Nav2 param YAMLs, and
recorded rosbags for regression. Rosbags and maps are versioned in-repo; large
bags gitignored. No Hub involvement.

## 7. Robium skills per build phase

| Phase | Skill(s) |
|---|---|
| Environment setup | environments |
| Robot model + bringup | ros2 |
| Simulation world | gazebo |
| Mapping + navigation | nav2 |
| Visualization | visualization → rviz2 (local), foxglove (remote) |
| Smoke/regression tests | testing |

## 8. Open risks

- **GPU availability unconfirmed** — the design assumes no GPU and stays on
  Gazebo, which is fine. Blocks nothing for this app, but confirm before any
  future perception/learning phase that might want Isaac. *Resolve:* check
  `nvidia-smi` on the dev/target machine.
- **Dynamic-obstacle avoidance in sim ≠ real** — Gazebo pedestrians are scripted;
  real warehouse traffic is messier. Blocks confidence in the avoidance tuning.
  *De-risk:* keep the costmap/controller params in `warehousebot_navigation`
  easy to retune; plan a hardware validation phase.
- **macOS + Gazebo rendering** — GUI rendering under Docker on macOS can be slow
  or flaky. Blocks smooth local dev. *De-risk:* prefer Foxglove/headless sim for
  day-to-day; use RViz2 sparingly, or move dev to the Linux workstation early.
- **ROS 2 Jazzy version pins** — Nav2/Gazebo package versions assumed compatible
  on the Jazzy line but not yet built. *Resolve:* stand up the Docker image
  first and confirm `colcon build` is clean before writing app code.

# Architecture brief template

The required structure of `docs/architecture-brief.md` — the living architecture
contract that lives in every robium application repo. The `robium-architect`
subagent writes the first version; all later refinement happens in the main
conversation with the `architect` skill loaded, editing this same file.

**Every section below is required.** Depth scales with the project (a one-robot
sim demo has a short comms plan; a fleet has a real one), but no section is
omitted — an empty section is a signal that a decision hasn't been made yet.
Copy the skeleton, fill each section, keep it current as the build proceeds.

---

## Skeleton

```markdown
# Architecture Brief — <app name>

**Date:** <YYYY-MM-DD>   **Status:** <draft | active | superseded>
**Author:** <robium-architect subagent | main agent refinement>

## 1. Requirements

The inputs this design answers to. Robot type, task, hardware, sim-vs-real,
GPU availability, local-vs-remote. Mark any assumed (not confirmed) input
explicitly — assumptions also feed section 8.

## 2. Chosen stack + reasoning

The decisions and why. One row per component with the alternative rejected.

| Layer | Choice | Version | Why (and what was rejected) |
|---|---|---|---|
| Middleware | ROS 2 / none | Jazzy | … |
| Simulator | Gazebo / Isaac / LeRobot-sim | Harmonic | … |
| Nav / learning | Nav2 / LeRobot / … | … | … |
| Visualization | rviz2 / foxglove / rerun | … | … |
| Environment | uv / Docker | … | … |

Tie each choice back to a branch in the architect stack-selection trees.

## 3. Module breakdown

The system decomposed into modules/packages/nodes, each with its
responsibility and its inputs/outputs. Mirrors the scaffold layout.

## 4. Comms plan

How modules talk. For ROS 2: the key topics/services/actions and their
message types and rates. For cross-process or remote boundaries: the
transport (topics vs zenoh vs gRPC). Sensor rates and frames that matter go
here. (The `integration` skill owns the detail.)

## 5. Environment strategy

Reproducibility. uv/venv vs Docker and why; base image or Python version;
GPU passthrough if any; how local and remote stay identical. (The
`environments` skill owns the detail.)

## 6. Data plan

Where data comes from and where it goes. Offline datasets vs sim-generated
vs teleop-collected; Hub datasets/models pulled or pushed; storage and
gitignore boundaries. For non-learning apps this may be short (maps, logs).
(The `data` and `huggingface` skills own the detail.)

## 7. Robium skills per build phase

The routing plan — which skill the builder loads at each phase, in order.
Example:

| Phase | Skill(s) |
|---|---|
| Env setup | environments |
| Robot model + bringup | ros2 |
| Simulation | gazebo |
| Navigation | nav2 |
| Visualization | visualization → foxglove |
| Testing | testing |

## 8. Open risks

Every unverified assumption and known unknown, stated plainly. GPU
availability, sim-to-real gap, hardware you can't inspect, version pins you
haven't confirmed, performance concerns. Each risk: what it is, what it
blocks, and how you'd resolve or de-risk it. This section is never empty —
if you think it is, you haven't looked hard enough.
```

---

## Filling notes

- **Section 2 is the heart.** A reader should be able to reconstruct why the
  stack is what it is without asking. Always name the rejected alternative.
- **Section 7 makes the brief actionable** — it is the routing table from the
  architect skill, narrowed to this app and ordered by build phase.
- **Section 8 protects the project.** The architect directive is to surface
  risks, not bury them. GPU availability is the most common one for the
  manipulation path; the sim-to-real gap for anything targeting real hardware.
- Keep **Status** current: `draft` while being written, `active` once the build
  is proceeding from it, `superseded` when a re-architecture pivot produces a
  new version (the subagent is relaunched only for genuine pivots).

See `examples/architecture-brief-example.md` for a filled instance.

# Scaffold patterns

Starting repo layouts for the two golden paths. Copy the tree, rename packages
to your app, prune directories you don't need. Two invariants hold for every
robium app regardless of stack:

- `docs/architecture-brief.md` — the living architecture contract. Fixed
  location; every build phase and the `robium-architect` subagent expect it here.
- `learnings/YYYY-MM-DD.md` — dated friction notes captured during building,
  later absorbed back into robium skills by `skill-author`.

The env layer (Dockerfile vs `pyproject.toml`) is decided by the `environments`
skill; both trees below show the common case.

## ROS 2 application (navigation golden path)

For a mobile robot navigating in Gazebo with Nav2. A ROS 2 workspace with a
`src/` colcon layout, one package per concern.

```
my-nav-robot/
├── docs/
│   └── architecture-brief.md        # the contract (required)
├── learnings/                       # dated friction notes for skill-author
├── docker/
│   ├── Dockerfile                   # ROS 2 Jazzy base + deps (environments skill)
│   └── compose.yaml                 # sim + nav + viz services
├── src/                             # colcon workspace source
│   ├── my_robot_description/        # URDF/xacro, meshes — the robot model
│   │   ├── urdf/
│   │   ├── meshes/
│   │   └── launch/                  # spawn/description launch
│   ├── my_robot_bringup/            # top-level launch + params, ties it together
│   │   ├── launch/                  # bringup.launch.py (sim + nav + viz)
│   │   └── config/                  # nav2_params.yaml, ros2 params
│   ├── my_robot_navigation/         # Nav2 config: costmaps, planners, BT
│   │   ├── config/
│   │   ├── behavior_trees/
│   │   └── maps/
│   └── my_robot_sim/                # Gazebo worlds + spawn glue
│       ├── worlds/
│       └── models/
├── tests/                           # smoke + launch tests (testing skill)
└── README.md
```

**What each dir holds**
- `*_description` — the robot's URDF/xacro, meshes, and the launch that
  publishes the model. One source of truth for the robot's geometry/frames.
- `*_bringup` — the composition layer: the launch file that starts sim + Nav2 +
  visualization together, plus the parameter YAMLs. Where a new user starts.
- `*_navigation` — everything Nav2 (`nav2` skill): costmap configs, planner and
  controller params, behavior trees, saved maps.
- `*_sim` — Gazebo (`gazebo` skill): world files, spawn models, sim-only glue.
- `docker/` — the reproducible environment (`environments` skill): a Jazzy base
  image and a compose file wiring the services.
- `tests/` — smoke and launch tests (`testing` skill): "does the robot reach a
  goal in sim" as a regression.

## LeRobot application (manipulation golden path)

For training and evaluating a manipulation policy. A Python project managed by
`uv` (no colcon), organized around the data → train → eval loop.

```
my-arm-policy/
├── docs/
│   └── architecture-brief.md        # the contract (required)
├── learnings/                       # dated friction notes for skill-author
├── pyproject.toml                   # uv-managed deps (environments skill)
├── uv.lock
├── src/
│   └── my_policy/
│       ├── configs/                 # policy + training configs (ACT, Diffusion, SmolVLA…)
│       ├── datasets/                # dataset prep / loading glue (huggingface delegation)
│       ├── train.py                 # training entry point (lerobot)
│       ├── eval.py                  # in-sim evaluation entry point
│       └── env/                     # sim/hardware env wrappers
├── data/                            # local datasets / cache (gitignored; data skill)
├── outputs/                         # checkpoints, logs, eval videos (gitignored)
├── notebooks/                       # exploration (optional)
├── tests/                           # smoke tests: dataset loads, 1-step train runs
└── README.md
```

**What each dir holds**
- `src/my_policy/configs` — training and policy hyperparameter configs; which
  policy family (ACT / Diffusion / SmolVLA / π0) and its settings.
- `src/my_policy/datasets` — glue for fetching and shaping datasets; Hub
  pulls/pushes go through the `huggingface` delegation, sourcing strategy
  through the `data` skill.
- `src/my_policy/{train,eval}.py` — the `lerobot` training and evaluation
  entry points; keep them thin, config-driven.
- `src/my_policy/env` — wrappers around the sim (or, later, real hardware).
  Add `isaac-sim`/`isaac-lab` here **only if the GPU floor is met**; otherwise
  LeRobot's own sim.
- `data/` and `outputs/` — large, regenerable, git-ignored.
- `pyproject.toml` + `uv.lock` — the reproducible env (`environments` skill);
  uv is the default for the manipulation path since much of it is CPU-friendly
  Python and doesn't need the full ROS 2 Docker apparatus.

## Adapting

- A real-hardware version of either app keeps the tree and swaps the `*_sim` /
  `env` directory for a hardware-driver package/module.
- A hybrid (learned policy running inside a ROS 2 system) starts from the ROS 2
  tree and adds a `my_policy` package that wraps the LeRobot inference.
- Prune aggressively for an MVP — a single-package ROS 2 demo doesn't need four
  packages. But never move `docs/architecture-brief.md`.

# Stack selection decision trees

The reasoning behind architect's routing table. Three decisions: middleware,
simulator, training framework. Each ends at a concrete, verified default and the
robium skill that owns the build. **Verify version facts against current docs
before committing them to a brief** — the defaults below were current as of
mid-2026 but robotics moves fast.

## Verified defaults (mid-2026)

| Component | Default | Why |
|---|---|---|
| ROS 2 distro | **Lyrical Luth** (general default); **Jazzy Jalisco** for the Nav2 vertical | Lyrical Luth is the current newest LTS (GA 2026-05-22, supported to May 2031) — default for new apps. Nav2 has not yet released binaries for Lyrical (tracked in `ros-navigation/navigation2#6123`), so the ROS 2 + Nav2 + Gazebo path still defaults to Jazzy Jalisco (LTS, supported to May 2029) until that lands. Kilted Kaiju is non-LTS and nearing its own EOL (~Dec 2026); don't pick it as a new default. |
| Simulator (ROS 2) | **Gazebo Jetty** with Lyrical; **Gazebo Harmonic** with Jazzy | Each is the officially paired sim for its ROS 2 distro, installed via ROS vendor packages. Both Jetty and Harmonic are themselves LTS Gazebo releases. |
| Manipulation learning | **LeRobot** (v0.6+) | Open, actively developed; supports ACT, Diffusion Policy, VQ-BeT, TDMPC, SmolVLA, π0/π0.5; ships sim + eval tooling; broad arm support (SO-100/101, Koch, LeKiwi, Reachy2). |
| GPU sim / RL | **Isaac Sim + Isaac Lab** | Only when the NVIDIA RTX GPU floor is met (see below); otherwise stay in LeRobot's sim. |

## Decision 1 — Middleware: ROS 2 or not?

```
Is the robot a mobile base / arm / multi-node system that needs
standard drivers, message passing, and an ecosystem of packages?
├─ Yes → ROS 2 (default Lyrical Luth; Jazzy Jalisco for the Nav2
│        vertical — see verified defaults above).  Route: ros2
│        Navigation on top?      → nav2
│        Needs a simulator?      → Decision 2
└─ No  → Is it a pure learning/policy problem with no runtime robot
         middleware (train a policy, evaluate in a learning sim)?
         ├─ Yes → skip ROS 2 for the MVP; LeRobot owns the loop. Route: lerobot
         └─ Unsure → default to ROS 2; it is the safer, more interoperable base
                     and nothing about it blocks adding a learning stack later.
```

**Notes**
- ROS 2 is the substrate for the navigation golden path. Even manipulation apps
  often add ROS 2 later for hardware drivers — but don't force it into an MVP
  that only needs to train and evaluate a policy.
- Middleware/comms choices *within* a ROS 2 app (topics vs services vs zenoh vs
  gRPC across process boundaries) are the `integration` skill's job, not this
  decision.

## Decision 2 — Simulator: Gazebo or Isaac?

```
Do you have a dedicated NVIDIA RTX GPU meeting the Isaac floor?
(RTX 4080+, 16 GB VRAM minimum, 32 GB+ system RAM, Linux — no macOS)
├─ No  → Gazebo Harmonic.  Route: gazebo   (the only viable ROS 2 sim here)
└─ Yes → What do you need the sim for?
         ├─ ROS 2 robot in a physics world, sensors, nav testing
         │     → Gazebo Harmonic is still the simpler, better-integrated
         │       choice for the nav vertical. Route: gazebo
         ├─ Photorealistic rendering / synthetic perception data
         │     → Isaac Sim. Route: isaac-sim
         └─ Massively parallel RL environments (thousands of envs on GPU)
               → Isaac Lab (on Isaac Sim). Route: isaac-lab
```

**Notes**
- Default to **Gazebo** unless there's a concrete reason to pay the Isaac cost
  (GPU requirement, driver setup, Linux-only, steeper learning curve). "It looks
  nicer" is not a reason for an MVP.
- If GPU availability is unconfirmed, do **not** design the MVP around Isaac —
  pick Gazebo (or LeRobot's own sim) and log the GPU question as an open risk.
- The `simulation` umbrella covers sensor-simulation correctness (noise, rates,
  frames) independent of which engine you pick.

## Decision 3 — Training / policy framework

```
Are you learning a control policy (imitation or RL)?
├─ No  → no training framework needed; classical nav/control via nav2/ros2.
└─ Yes → What kind?
         ├─ Imitation / behavior cloning from demos (teleop or datasets),
         │  manipulation especially
         │     → LeRobot. Route: lerobot   (+ huggingface for data/models)
         ├─ Reinforcement learning at scale, GPU available
         │     → Isaac Lab. Route: isaac-lab
         └─ Small-scale RL / no GPU
               → LeRobot's tooling or a lightweight gym; keep it CPU/uv.
```

**Data sourcing** for any learning path is the `data` skill's call — offline
datasets vs sim-generated vs teleop-collected — and Hub pulls/pushes go through
the `huggingface` delegation (`hf-cli@huggingface-skills`).

## Where each decision is recorded

Every branch you take becomes a line in `docs/architecture-brief.md` under
"chosen stack + reasoning". An unresolved branch (GPU unknown, distro pinned by
an external dependency you haven't confirmed) becomes an entry under "open
risks". See `brief-template.md`.