How the environment fits together
The Mac provides the interactive workspace and Orca interface. Shipyard runs native agent/application processes and Docker dependencies. This keeps project toolchains recognizable and avoids turning an entire development shell into a container.
Open the architecture explorer. The overview shows machines; select a focused view for service detail. Diagrams describe recorded architecture, not current health or a list of running containers. Select a component to open its operating guide.
Pan and zoom in the diagram, or open it full screen. Each text and JSON view below is generated from the same model. Text views list the underlying connections even when a diagram groups them together. JSON includes stable component IDs, inventory evidence and operating-guide links.
| View | Diagram | Readable text | Agent data |
|---|---|---|---|
| Environment | Open | Text | JSON |
| Shipyard services | Open | Text | JSON |
| Development tasks | Open | Text | JSON |
| API | Open | Text | JSON |
| Search engine | Open | Text | JSON |
| Browser control | Open | Text | JSON |
| Home test bed | Open | Text | JSON |
| Test bed data and cloud | Open | Text | JSON |
| Build and swap | Open | Text | JSON |
For the order of setup, work and archive, see the task lifecycle.
Boundaries
Section titled “Boundaries”| Boundary | Responsibility | Persistence |
|---|---|---|
| Mac | Orca UI, local repositories, SSH client | Independent local files and credentials |
| Shipyard | Native agents, applications, builds, Docker | Survives SSH and Orca disconnection |
| API workspace | API process and isolated Docker services | Checkout plus retained named volumes |
| Dashboard companion | Separate Git checkout and dependencies | Moved outside API tree on managed archive |
| Shared browser | Chromium profile, Playwright and noVNC | Login profile survives browser restart |
| Appliance workspace | Runtime and separate test dependencies | State/volumes outside removed checkout |
| Build server (home) | Simulated cameras, webhook receiver, host-side Rust builds | Library, logs and build cache under /home/pi |
| Edge appliance (home) | The Spot NVR under test; containers from the product | /data; configs owned by the cloud |
Why this arrangement
Section titled “Why this arrangement”- Native application commands keep ordinary development behavior, including API reload.
- Containers isolate databases and service dependencies without sharing mutable node_modules across branches.
- API setup is serialized to control peak memory. Appliance builds share a locked cache but copy each runtime executable.
- Dashboard is opt-in because only one preview is needed and its workers are a significant memory cost.
- Staging refresh updates the primary local seed. New worktrees clone local seed data; routine restart never silently reseeds.
- Generated workspace instructions put task-specific commands in front of agents. This repository supplies the broader context and recovery knowledge.
Logical and physical views
Section titled “Logical and physical views”The diagrams use C4-inspired context, deployment and runtime views. A physical host is a host, a service is running software, and a workspace is a repeatable task boundary. The model does not equate C4 containers with Docker containers. Protocol labels describe how components interact; they do not grant permission to access them.
The inventory owns operational facts. The architecture model owns relationships. Decisions explain tooling choices.