Directory Atlas: draft repo layouts under RFC #379 + #380

[andrewjong]

Directory Atlas: draft repo layouts under RFC #379 + #380

Companion visualization to RFC #379: Modular AirStack and RFC #380: Heterogeneous AirStack. Those RFCs describe the design in prose; this discussion shows what the repositories would actually look like once both land — seven repo shapes, one page. Draft for discussion: file names are illustrative, anatomies are normative.

Legend — untagged entries exist in trunk today:

Marker	Meaning
[new]	added by this design
[gen]	generated — never hand-edited
[ign]	gitignored — local to the machine
(#379 §n)	section in the owning RFC

How a checkout resolves

One hand-edited file selects everything; everything else is derived, fetched, or observed. This pipeline is the reading order for the trunk tree below:

airstack.yaml ──▶ airstack sync ──▶ airstack up ──▶ doctor --live ──▶ .airstack/runs/
release, fleet,   resolves pins →    composes images   observed graph    every run dumps
sim, extra        modules.lock,      from module        vs each stack's   effective_config.yaml;
modules, stack    .env; fetches      layers; launches   wiring.md +       `config freeze`
repos (#380 §3)   modules/ + stacks  stack entry points bridge lists      promotes it

1. Trunk checkout — castacks/AirStack

Trunk keeps the base images, the test harness, the reference stacks, and the modules that haven't migrated out yet. It never carries external module code — that arrives per-stack, gitignored.

AirStack/
├── airstack.yaml               [new]        the one hand-edited entry point: release, fleet, sim, extra modules,
│                                            external stack repos (#380 §3)
├── .env                        [gen]        emitted by sync — today's hand-edited env vars become derived
├── modules.lock                [new][gen]   exact refs + image digest chain per module
├── modules/                    [new][ign]   module checkouts synced from the active stacks' modules.repos (#379 §3)
│   ├── optitrack/                           ← a module repo checkout (anatomy in §2 below)
│   └── dfm2_disturbances/
├── stacks/                     [new]        trunk's REFERENCE stacks only — others live in their owners' repos (#379 §3)
│   ├── full_default/                        the current full-autonomy topology, as a folder
│   │   ├── modules.repos                    vcstool format, PINNED to tags/commits — a localized release set;
│   │   │                                    optional airstack_compat: key = trunk range tested against (#379 §3)
│   │   ├── launch/
│   │   │   └── stack.launch.xml             THE wiring document — all remaps live here, nowhere else (#379 §4)
│   │   ├── docker-compose.yaml              composes this stack's images from module layers (#379 §6)
│   │   ├── wiring.md           [gen]        mermaid dataflow snapshotted from the RUNNING graph in CI; drift-checked
│   │   └── README.md
│   ├── lite_default/                        onboard-lite counterpart
│   ├── full_droan_cpu/                      ┐ presets absorbing today's local_*.launch.xml
│   ├── full_macvo/                          ┘ variant explosion — a few include lines apart
│   ├── lite_offload_global/                 a SPLIT stack — multiple entry points (#380 §2)
│   │   ├── modules.repos
│   │   ├── launch/
│   │   │   ├── onboard.launch.xml           runs on the robot
│   │   │   └── offboard.launch.xml          runs on the ground host named by the fleet
│   │   ├── bridge.yaml                      every topic/action crossing the machine boundary → DDS-router config
│   │   ├── docker-compose.yaml
│   │   ├── wiring.md           [gen]        ONE per stack, split or not — nodes grouped by host/entry point,
│   │   │                                    bridge edges marked (#379 §4)
│   │   └── README.md
│   ├── gcs_ui/                              operator ground station stack
│   └── .external/              [new][ign]   stack repos fetched by sync — fleets address their stacks as
│                                            <alias>/<stack> (#380 §3)
├── config/
│   ├── fleets/                 [new]        who exists, which body, which brain, which hosts (#380 §2)
│   │   ├── field_mixed.yaml                 robots = vehicle × stack × unit; named ground hosts; network
│   │   └── sim_three_quads.yaml             replaces NUM_ROBOTS + ISAAC_SIM_SCRIPT_NAME
│   ├── vehicles/               [new]        in-tree vehicle types; others arrive as data modules (#380 §1)
│   │   └── quad_small/
│   │       ├── vehicle.yaml                 platform, airframe, sensor suite, sim_asset
│   │       ├── mounts/                      sensor extrinsics (front.yaml, belly.yaml, …)
│   │       ├── tuning/                      controller tuning per vehicle, like PX4 airframe files
│   │       └── xacro/                       base xacro — URDF is GENERATED from base + mounts
│   └── local/                  [new][ign]   this machine only — never shared
│       ├── calibration/SN-0042/             per-serial intrinsics/extrinsics; field-updated
│       └── overrides.yaml                   4th precedence layer, below CLI flags (#380 §3)
├── .airstack/                  [new][ign]
│   └── runs/<timestamp>/
│       └── effective_config.yaml [gen]      fully-resolved config of every run; `config freeze` promotes it (#380 §4)
├── robot/
│   ├── docker/                              base image — Dockerfile.robot THINS as deps migrate into modules
│   └── ros_ws/src/
│       ├── interface/ sensors/ perception/
│       │   local/ global/ behavior/         trunk-resident modules; launch args default to canonical topics;
│       │                                    candidates migrate out over time
│       ├── autonomy_bringup/                thins — AUTONOMY_ROLE dispatch replaced by stack entry points
│       └── modules/            [new][ign]   overlay symlinks into ../../modules/ — colcon picks them up
├── gcs/  simulation/isaac-sim/  simulation/ms-airsim/
│                                            host containers stay machines; sim EXTENSIONS arrive as modules
├── common/
│   └── airstack_msgs/                       ruthlessly semver'd as its own package (#379 §8)
├── tests/                                   existing harness + wiring-snapshot step + fleet presets
│                                            (--fleet replaces --num-robots)
├── docs/
│   └── robot/autonomy/
│       └── interface_conventions.md [new]   integration_checklist.md upgraded: canonical topics + types +
│                                            QoS + frames (#379 §4)
├── .github/
│   ├── workflows/
│   │   └── module-system-tests.yml [new]    reusable workflow — a module repo's entire CI calls this (#379 §5)
│   └── orchestrator/                        OSMO ephemeral GPU runners (exists today)
└── .agents/skills/                          create-stack + extract-module added; write-launch-file & friends
                                             re-taught (#379 §10)

Gone from the tree, absorbed elsewhere: AUTONOMY_ROLE, NUM_ROBOTS, URDF_FILE, ROBOT_NAME_MAP_CONFIG_FILE, and ISAAC_SIM_SCRIPT_NAME as hand-set env vars — all derived from airstack.yaml → fleet → stack resolution (#380 §3 migration table).

2. A module repo — e.g. castacks/airstack-optitrack

A thin repo: ordinary colcon packages, a small manifest carrying deps and identity only — no wiring metadata — and a test_stack/ that is both its CI target and its living install documentation.

airstack-optitrack/
├── module.yaml                              name, maintainer, license, type, airstack_compat, deps, tests —
│                                            nothing about wiring (#379 §2)
├── natnet_ros2/                             ordinary colcon package(s)
│   ├── package.xml                          rosdep keys live here (dep tier 1)
│   ├── src/
│   ├── launch/
│   │   └── optitrack.launch.xml             topic args DEFAULT to canonical names
│   │                                        (odom_out → /$ROBOT_NAME/odometry); never remaps
│   ├── config/params.yaml
│   └── test/                                co-located unit tests, standard colcon convention
├── test_stack/                              reference stack copy with this module wired in —
│   │                                        same 5-file anatomy as any stack (#379 §5)
│   ├── modules.repos                        pins the module's siblings for the test bring-up
│   ├── launch/stack.launch.xml              the one place this module is wired —
│   │                                        the install snippet IS a working stack
│   ├── docker-compose.yaml
│   ├── wiring.md               [gen]
│   └── README.md
├── Dockerfile.module                        optional dep tier 2 — written against ARG BASE_IMAGE,
│                                            never a fixed base (#379 §6)
├── .github/workflows/
│   └── ci.yml                               ~10 lines: uses castacks/AirStack/.github/workflows/
│                                            module-system-tests.yml@v0.19.0
└── README.md                                validated against the template at registration;
                                             embedded on the docs site (#379 §9)

A heavyweight module (20 GB CUDA deps) adds nothing here — its CI publishes an overlay image (overlay_image: in the manifest, dep tier 3) and developers pull instead of build.

3. A lab's stack repo — e.g. airlab-internal/swarm-stacks (private)

Stack folders are self-contained, so a custom topology needs no fork of AirStack anywhere — a private repo of stacks and fleets wiring together public (and private) modules. This is the heterogeneous-fleet story: each robot points at a stack, wherever that stack is hosted.

swarm-stacks/
├── stacks/
│   ├── vla_offload/                         end-to-end VLA — its launch simply doesn't include
│   │   │                                    the planning pipeline
│   │   ├── modules.repos                    pulls vla_pilot + the same public interface/estimation modules
│   │   ├── launch/
│   │   │   ├── onboard.launch.xml
│   │   │   └── offboard.launch.xml          the VLA model runs on the edge box
│   │   ├── bridge.yaml                      doctor rejects control_setpoint / trajectory topics
│   │   │                                    in any bridge list (#380 §2)
│   │   ├── docker-compose.yaml
│   │   ├── wiring.md           [gen]        generated by the SAME reusable workflow trunk uses
│   │   └── README.md
│   └── cbf_swarm/                           another topology, same anatomy
├── fleets/
│   └── canyon_demo.yaml                     hexa mapper + two lite quads; consuming checkouts declare this
│                                            repo under airstack.yaml stacks: and reference its stacks as
│                                            swarm_stacks/vla_offload etc. (#380 §3)
└── .github/workflows/ci.yml                 owners test their own stacks — trunk CI covers
                                             reference stacks only (#379 §5)

A stack that can't run in CI (hardware-only sensors, no sim asset) still commits an observed wiring.md: doctor --snapshot captures a real bring-up and commits it with a provenance line; the drift check reports it as unverified-in-CI instead of silently passing (#379 §4).

4. A vehicle module — e.g. castacks/vehicle-hexa-big (module type: data)

A vehicle type is data, distributed through the same module mechanism. Each sensor entry names its real driver and its sim representation — one source of truth for both worlds.

vehicle-hexa-big/
├── module.yaml                              type: data — no code, no launch (#379 §2)
├── vehicle.yaml                             platform: px4_multirotor; airframe (xacro + mass + tuning);
│                                            sensors; sim_asset (#380 §1)
├── mounts/                                  per-sensor extrinsics
├── tuning/hexa_big.yaml
├── xacro/hexa_680.xacro                     URDF generated from this + mounts — no monolithic
│                                            hand-built URDF
├── sim/hexa_680.usd
└── README.md

What is not here: calibration. Intrinsics/extrinsics are per-serial-number and live in each machine's gitignored config/local/calibration/<serial>/ — recalibrating in the field never edits the shared package.

5. A platform module — e.g. castacks/platform-unitree-go2 (module type: platform, future — #380 Part 2)

Sequenced after #379's phases 1–4 are proven: the embodiment layer as the biggest module. It ships the hardware interface, controller, safety behaviors, and its own reference stacks. The PX4 multirotor stack becomes the first one, extracted from trunk while it's still the only platform.

platform-unitree-go2/
├── module.yaml                              type: platform; traits {workspace, hover_capable, …};
│                                            safety_map; provides_tasks; provides_dialects (#380 §6)
├── go2_interface/                           vendor SDK bridge
├── go2_controller/                          command dialects: trajectory_se2, twist
├── go2_safety/                              maps abstract states → behaviors: SAFE_STOP→sit,
│                                            RTB→walk_home, KILL→motor_cut (#380 §7)
├── go2_description/
├── stacks/
│   └── go2_default/                         the platform's own reference stack — same 5-file anatomy
├── sim/                                     isaac asset + SITL glue — each platform ships its
│                                            sim integration (#380 §8)
└── README.md

6. The registry — castacks/airstack-modules-index

The rosdistro pattern: one YAML per entry, a PR to get listed, CI-generated compat matrices. The docs site renders it as the marketplace catalog.

airstack-modules-index/
├── modules/
│   ├── optitrack.yaml                       name, repo URL, maintainer, description (#379 §7)
│   ├── dfm2_disturbances.yaml
│   └── vehicle-hexa-big.yaml
├── stacks/                                  registered stacks get catalog entries + embedded wiring.md
├── compat/                     [gen]        badge matrix stamped by conformance CI runs —
│                                            never hand-claimed (#379 §5)
├── releases/
│   └── 0.20.yaml                            a release set = tagged reference-stack pins,
│                                            blessed by one CI run (#379 §7)
├── rfcs/                                    conventions-spec deprecation RFCs — changing a canonical
│                                            topic/QoS/frame lands here first (#379 §8)
└── unmaintained/                            the shelf: canary red N weeks unanswered moves an entry
                                             here, labeled — not green-badged

7. The researcher fork, before graduation — Stage 1 of #379 §11

Research happens in a fork; modularity is a graduation step, not an entry fee. The only day-one discipline is a directory boundary — everything else is deferred until extraction.

AirStack/                                    (fork, pinned via `airstack init --release 0.20`)
└── robot/ros_ws/src/modules/
    └── my_planner/                          scaffolded by `module create --in-tree` —
        │                                    a real dir here, not a symlink
        ├── module.yaml                      stub — zero CI/registry obligations at this stage
        ├── package.xml  src/  config/  test/
        └── launch/my_planner.launch.xml     canonical defaults from day one

doctor --drift diffs the fork against the pinned release: changes inside my_planner/ are fine; trunk edits are listed as extraction debt. module extract my_planner then moves the directory into a fresh module repo (shape 2 above) with the drift report as the task list.

---

Sources: RFC #379 (module anatomy §2, stacks §3, legibility §4, CI §5, Docker §6, registry §7, researcher workflow §11) and RFC #380 (vehicles §1, fleets §2, top-level config §3, platform modules §6). Layouts reflect the design as of 2026-08-20 (updated for the RFCs' consistency pass: external stack repos, airstack_compat: in modules.repos, split-stack wiring.md grouping, hardware wiring.md provenance); feedback on naming and placement welcome here, design feedback belongs on the RFCs.

[andrewjong]

Changelog (2026-08-20)

Trees updated to match the RFCs' consistency pass (#379, #380):

• Resolution pipeline + airstack.yaml comments now include external stack repos (stacks: — RFC: Heterogeneous AirStack — vehicle configs, fleets, top-level configuration, and cross-embodiment platforms #380 §3), and the trunk tree gains stacks/.external/ [new][ign].
• modules.repos entries note the optional airstack_compat: key (trunk range the stack was tested against — Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs #379 §3).
• The split stack's wiring.md is annotated one per stack — nodes grouped by host/entry point, bridge edges marked.
• §3 (lab stack repo): fleets are consumed via an airstack.yaml stacks: alias (swarm_stacks/vla_offload); new note on hardware-only stacks committing an observed wiring.md via doctor --snapshot (unverified-in-CI).