# Repository layout

> Where each RosieOS component lives in the repository, which versioned folders are current and which are legacy, and which files are generated from contracts rather than edited by hand.

URL: https://advancedmetalresearch.com/docs/contributing/repo-layout
Section: RosieOS docs / Contributing
Last updated: 2026-10-10

RosieOS is one repository with a folder per component. There is no root build: each component builds and tests on its own with its own tool (`make`, `go`, `npm`, `pixi`). Many folders are versioned (`v1`, `v4`, `v5`). Only some versions are current. This page tells you which.

```bash
git clone https://github.com/advanced-metal-research/RosieOS.git
cd RosieOS
```

## Current components

| Folder | Language | What it is | Docs |
|---|---|---|---|
| `rt-core/` | C++17, Go | The real-time core (`rosie-rt-core`, `rosie-rt-core-sim`), the public control API `rt-control`, the Go SDK, C++ and TypeScript clients, `rtctl`, host install scripts and all rt-core configuration | [Real-time core](https://advancedmetalresearch.com/docs/concepts/real-time-core), [rt-control HTTP API](https://advancedmetalresearch.com/docs/apis/rt-control-http) |
| `robot_description/` | data, Go, Python | One directory per robot model, the Go module `rosieos/robotdesc` and the manifest tool | [Robot description](https://advancedmetalresearch.com/docs/concepts/robot-description-and-frames) |
| `motion-server/v1/` | C++17 | The Cartesian motion server `robot-v4-cartesiand` | [Cartesian motion server](https://advancedmetalresearch.com/docs/apis/cartesian-motion-server) |
| `motion-server/joint-trajectory/v1/` | C++17 | The dense trajectory daemon | [Dense trajectory daemon](https://advancedmetalresearch.com/docs/apis/dense-trajectory-daemon) |
| `offline-programming/v1/` | Go; `ui/` TypeScript | The offline programming (OLP) server and browser app | [OLP HTTP API](https://advancedmetalresearch.com/docs/apis/olp-http) |
| `weld_planner/v1/` | Python (pixi) | Seam worker, CUDA weld motion planner and verifier, `weldplan` contracts | [Weld planner HTTP API](https://advancedmetalresearch.com/docs/apis/weld-planner-http) |
| `tesseract/v1/`, `cadquery/v1/` | Python (pixi) | Planning and CAD environments used by the motion server and OLP | [Install the toolchain](https://advancedmetalresearch.com/docs/get-started/installation) |
| `steamdeck/real/v5/` | C++/Qt | The Steam Deck teach pendant. Not qualified for real motion. | [Program from the pendant](https://advancedmetalresearch.com/docs/guides/program-from-the-pendant) |
| `steamdeck/real/v4/` | Go, C++ | The native deploy module (`go run .`) and the v4 rollback pendant | — |
| `steamdeck/virtual/` | TypeScript, Go | The browser pendant and its bridge, for simulation only | [Virtual pendant](https://advancedmetalresearch.com/docs/guides/virtual-pendant) |
| `urdf/v1/` | TypeScript | URDF tooling; `sphere_tool/` authors collision spheres | [Add a robot model](https://advancedmetalresearch.com/docs/guides/add-a-robot-model#spheres) |
| `dev-stack.sh` | Bash | Starts the local simulated stack | [Run everything in simulation](https://advancedmetalresearch.com/docs/guides/run-in-simulation) |
| `quality/` | Node | Lint, format and report runners | [Code style and quality](https://advancedmetalresearch.com/docs/contributing/code-style) |
| `tools/robot-stack-release/`, `releases/` | Python, JSON | Release bundling and release records | [Releasing](https://advancedmetalresearch.com/docs/contributing/releasing) |
| `.github/workflows/` | YAML | CI | [Building and testing](https://advancedmetalresearch.com/docs/contributing/building-and-testing#ci) |

Also in the tree and installed alongside a cell, but not documented here: `daemon/v1` (the mesh daemon and program catalogue), `nats/v1`, `mujoco-sim/v1` (an experimental physics model), `preflight/` and `coordination/v1` (internal tooling).

### Inside `rt-core/`

| Path | Holds |
|---|---|
| `src/main.cpp`, `engine/`, `include/` | The cyclic core. Header-only engine. |
| `cmd/rt-control/`, `adapters/rosie/control/` | `rt-control` and the public API implementation. |
| `ipcclient/` | The Go side of the private core IPC. |
| `sdk/control/` | The public Go SDK. |
| `clients/cpp/`, `clients/ts/` | Header-only C++ client; TypeScript types and telemetry decoders. |
| `protocol/` | The two contracts: `control.json` (private IPC) and `application-v1.schema.json` (public API). |
| `config/` | `drives/`, `machines/`, `cells/`, `cell-io/` and `templates/`. |
| `host/` | Install scripts and systemd units. |
| `tools/` | `rtctl`, `benchdrive`, `natspublisher`, the generators, packaging and `rdtcheck`. |
| `tests/`, `simfixture/` | C++ policy tests and the Go simulation fixture. |

## Generated code

Some files are generated from a contract. Edit the contract and regenerate; never edit the output. `make check-protocol` and `make check-api` fail on drift, and both run in `make test`.

| Contract | Generator | Outputs |
|---|---|---|
| `rt-core/protocol/control.json` | `make -C rt-core generate-protocol` (`tools/protocolgen`) | `ipcclient/protocol_generated.go`, `clients/cpp/include/rosie/protocol_generated.hpp` (and the `include/protocol_generated.hpp` shim), `clients/ts/rt_protocol_generated.ts` |
| `rt-core/protocol/application-v1.schema.json` | `make -C rt-core generate-api` (`tools/apigen`) | `adapters/rosie/control/api_generated.go`, `clients/cpp/include/rosie/rt_control_api_generated.hpp`, `clients/ts/rt_control_api_generated.ts` |

The generators compare the TypeScript output against goldens using Node 22.13.1. They look for it at `~/.rosie/node-22.13.1/bin/node` or in `NODE`.

## Legacy folders

These are earlier generations. No current code references them. Do not build on them.

| Folder | What it was |
|---|---|
| `robot/v1` to `robot/v10` | Earlier robot CLIs, stacks and third-party arm scaffolds |
| `daemon/v2` | An earlier mesh daemon |
| `urdf/v2` to `urdf/v5` | Earlier CAD-to-URDF experiments |
| `steamdeck/real/v1` to `v3` | Earlier pendant demos |
| `rt-core/docs/history/`, `rt-core/docs/evidence/` | Dated design and run records |

The retired v4 real-time core, its NATS command bridge and the OLP's connected-execution path over NATS are also legacy. OLP keeps the last behind flags that are off by default.

## Things that are not in this repository

- **The `rosie` CLI.** Many READMEs show `./rosie.sh …`, `.\rosie.ps1 …` or `rosie … v1 …`. That tool lives in an internal repository and those commands do not work from a clone. Use the per-component commands in [Building and testing](https://advancedmetalresearch.com/docs/contributing/building-and-testing).
- **A root `go.mod`, `go.work` or build dispatcher.** Go modules are per component: `rt-core/go.mod` (`rosieos/rt-core`), `robot_description/go/go.mod` (`rosieos/robotdesc`), and one each in `offline-programming/v1`, `steamdeck/real/v4` and `steamdeck/virtual`. `rt-core` reaches `robot_description/go` through a `replace` directive.
- **Toolchain management.** Install Go, Node, pixi, uv and a C++17 compiler yourself. See [Install the toolchain](https://advancedmetalresearch.com/docs/get-started/installation).

## Sources

Written from these files in the RosieOS repository (https://github.com/advanced-metal-research/RosieOS):

- `rt-core/go.mod:1-13`
- `robot_description/go/go.mod`
- `rt-core/Makefile:224,296-315`
- `rt-core/tools/protocolgen/generate.go:380-396`
- `rt-core/tools/apigen/main.go:405-452`
- `rt-core/cmd/rt-control/main.go:24-39`
- `dev-stack.sh:76`
- `offline-programming/v1/main.go:35,80-96,272-281`
- `steamdeck/real/v4/cli.go:128-178`
- `quality/quality.mjs:1-110`
- `.github/workflows/rt-core.yml:29-37`
- `urdf/v1/sphere_tool/package.json`