<!-- 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) | n/a | 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 with 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 decision record template

Use `docs/architecture-brief.md` for a new application or a genuine
re-architecture. It records decisions and uncertainty; it is not an immutable
contract. Update it when evidence authorizes a pivot.

Only the four core sections are required. Add optional detail when it changes a
decision or helps the next implementation step.

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

**Date:** <YYYY-MM-DD>
**Status:** <draft | active | superseded>

## Goal and constraints

The user-visible outcome, robot/task, sim-vs-real target, available hardware,
GPU/budget limits, and local/remote constraints. Mark unconfirmed inputs as
provisional.

## Decisions

| Decision | Choice | Why now | Confidence |
|---|---|---|---|
| First working slice | ... | Cheapest useful risk reduction | validated/provisional |
| Environment | uv/Docker/... | ... | validated/provisional |
| Simulator/middleware | ... | ... | validated/provisional |

Include an alternative only when it was a genuine contender. Do not invent a
rejected option to make the record look complete.

## Provisional assumptions and risks

| Assumption or risk | Impact | Cheapest validation | Authorized pivot |
|---|---|---|---|
| ... | ... | ... | What may change without a new design gate |

## Implementation path

1. The smallest user-visible or risk-reducing slice.
2. The smoke check that proves it.
3. The next integration step if it passes.
```

## Optional sections

Add only those the application needs:

- **Module boundaries and communications** for multi-process, ROS 2, remote, or
  multi-container systems.
- **Environment and deployment detail** when GPU, system dependencies, or
  local/remote parity is a real risk.
- **Data lifecycle** for dataset sourcing, storage, recording, publication, or
  model artifacts.
- **Skill routing** when several Robium skills will be used across phases.
- **Alternatives considered** for a material product or stack choice.

## Updating the record

- Replace a provisional assumption with evidence as soon as a cheap probe
  resolves it.
- Treat a failed probe as information, not a specification violation. Use the
  documented authorized pivot when it remains within the approved direction.
- Ask for another direction decision only when the evidence creates a material
  product choice, scope expansion, external-cost action, or safety concern.
- Set the record to `superseded` only for a genuine re-architecture. Ordinary
  implementation discoveries are normal edits to the active record.

See `../examples/architecture-brief-example.md` for a filled instance; older
examples may be more detailed than a small project requires.

# Scaffold patterns

Starting repo layouts for the two golden paths. Copy the closest verified app
from the robium-apps registry when one exists; otherwise use these trees. Rename
packages and prune anything the first working slice does not need.

New applications keep a concise decision record at `docs/architecture-brief.md`.
Learning capture belongs to Robium's sibling `learnings/` tree and hooks rather
than an application-local ritual.

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        # concise decision record
├── 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        # concise decision record
├── 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. Keep the decision record at `docs/architecture-brief.md` for new
  applications and genuine re-architecture work.

# 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 self-contained `huggingface` skill.

## Where each decision is recorded

Material branches become concise decisions in `docs/architecture-brief.md`.
Unresolved high-impact branches (GPU unknown, a version pin constrained by an
unverified dependency) remain provisional assumptions with a cheap validation
step and an authorized pivot. See `brief-template.md`.