Appendix
Appendix E: Reference Architecture
A single, large, annotated diagram of the lab's architecture with all components, ports, paths, and communication flows. The single page to print.
Purpose
This appendix is the single annotated diagram of the lab's architecture. It complements the System Architecture page with a single, large, printable view.
The diagram is sanitized: real names, real paths, and
real agent identifiers are replaced with placeholders.
The places where the placeholders go are marked with
{...}.
The diagram
Loading diagram…
Click any box to open its documentation page.
Annotated components
External services
| Component | Protocol | Purpose |
|---|---|---|
| Model Provider A | HTTPS | The Coordinator's primary model. |
| Model Provider B | HTTPS | The Coordinator's fast variant. |
| Search Provider: Tavily | HTTPS | The research framework's primary search adapter. |
| Search Provider: DuckDuckGo | HTTPS | The fallback search adapter. |
| Search Provider: Google | HTTPS | The optional Google Custom Search adapter. |
| Video: YouTube | HTTPS | YouTube search and transcript. |
| Streaming: Stremio | mDNS | Stremio catalog and streaming. |
| Chromecast Devices | mDNS | Cast-capable displays on the LAN. |
| VLC Hosts on LAN | mDNS | VLC instances with RC/HTTP enabled. |
Gateway layer
| Component | Port | Purpose |
|---|---|---|
| Coordinator | 18789 | The main gateway. The user's entry point. |
| Scout | 18790 | The specialized gateway for the Research Worker and the Media Agent. |
Agent layer
| Component | Purpose |
|---|---|
| Coordinator | Routes requests, manages memory and sessions, activates skills. |
| Coding Assistant | Reviews code from the sub-agent, integrates, tests. |
| Research Worker | Runs research missions end-to-end. |
| Media Agent | Handles media search and playback to local and remote devices. |
| Web Agent | Drives the browser through the accessibility tree. |
Framework layer
| Component | Purpose |
|---|---|
| Research Framework | Orchestrates the 8 phases; manages artifacts, state, and the request journal. |
| Coding Sub-agent | The sandboxed Codex CLI that the Coding Assistant delegates to. |
Tool layer
| Component | Purpose |
|---|---|
| CLI tools | The lab's deterministic CLI tools (torrent-finder, etc.). |
| chromecast | Discovers and controls Cast devices. |
| vlc | Spawns and controls VLC locally and remotely. |
| media-playback | Selects the right backend for a given source. |
| media-lab-server | Generates images and music through an HTTP API. |
| browser | Drives a Chromium-based browser. |
Adapter layer
| Component | Purpose |
|---|---|
| tavily | Search adapter for Tavily. |
| duckduckgo | Search adapter for DuckDuckGo. |
| google_search | Search adapter for Google Custom Search. |
| youtube_transcript | Transcript adapter for YouTube. |
| yt-dlp | Fallback video metadata adapter. |
| perplexity | Synthesis adapter with a token pool. |
State layer
| Component | Purpose |
|---|---|
| MEMORY.md | The lab's long-term memory. |
| Daily logs | The raw chronological record. |
| Session state | The in-memory state of the current session. |
| Skills | The agent's capabilities (SKILL.md, TOOL.md). |
| Mission artifacts | The research framework's typed outputs. |
| Request journal | The append-only log of external calls. |
| Token pool state | The live state of the token pool. |
| Audit reports | The weekly, monthly, quarterly, and ad-hoc audits. |
How to read the diagram
- User is the only external entity. The user communicates with the Coordinator through the Coordinator gateway.
- Coordinator gateway is the entry point. The Coordinator itself runs inside the gateway process.
- Scout gateway hosts the Research Worker and the Media Agent. The Coordinator talks to the Scout through HTTP.
- Coding sub-agent is invoked by the Coding Assistant. The sub-agent runs in a sandbox.
- Web Agent drives the browser through the OpenClaw browser tool on the CDP port.
- Media Lab Server is a standalone HTTP server
(
:8765) that the Coordinator can call directly. - State layer is the foundation. Every other layer reads from and writes to the state layer.
What the diagram does not show
- Per-process supervision (launchd, systemd).
- Configuration file locations (see Environment Variables).
- Specific commands (see the Runbook).
- Failure modes (see Failure Catalog).
The diagram is a single view of the system. The details are in the other pages.