System Architecture

The detailed view — the 8-layer model, runtime processes, directory layout, communication paths, and deployment topology.

Purpose

This page is the lab's technical architecture reference. It complements the high-level System Overview with concrete details on processes, ports, directories, and communication paths.

The 8-layer model

The lab is organized in 8 layers. Each layer has a single responsibility, a clear contract with adjacent layers, and is independently testable.

Loading diagram…

The 8-layer model — a top-to-bottom stack from User Interface to External; the dotted edges are the interior layers reading and writing State.

Layer	Name	Responsibility
1	User Interface	Natural-language input/output. Sessions, prompts, results.
2	Coordination	Intent resolution, routing, memory, session, skills.
3	Agent	Specialized roles (Research, Coding, Media, Web).
4	Framework	Domain orchestration (Research Framework, Coding sub-agent).
5	Tool	Typed, deterministic capabilities (CLI tools, MCP adapters).
6	Adapter	Provider-specific translation (Tavily, DuckDuckGo, etc.).
7	State	Memory, sessions, skills, artifacts, audit trail.
8	External	Model providers, search providers, streaming services, devices.

The contract between adjacent layers is documented in the Framework page.

Runtime processes

The lab has the following runtime processes:

Process	Owner	Port	Lifespan	Restart policy
Coordinator gateway	Coordinator	18789	Always on	launchd / systemd
Scout gateway	Research Worker + Media Agent	18790	Always on	launchd / systemd
Coding sub-agent	Coding Assistant	n/a	Per-invocation	Re-spawned each call
Browser (Chromium)	Web Agent	18800	On demand	Restarted on crash
Media Lab Server	Coordinator (or any agent)	8765	On demand	Manual or launchd
Tool processes	Various	n/a	Per-call	Re-spawned each call

The two gateways are the only long-running processes. Everything else is short-lived.

Directory layout

The lab's directory layout is:

{workspace-root}/
├── .openclaw/                  ← framework state
│   ├── openclaw.json           ← main config
│   ├── workspace/              ← main workspace (Coordinator)
│   ├── workspace-scout/        ← Scout workspace
│   ├── agents/                 ← agent configs
│   ├── plugin-skills/          ← bundled skills
│   └── media/                  ← Media Lab outputs
│       └── outbound/
├── devclaw-tools/              ← tool repos
│   ├── audio-server/           ← Media Lab Server
│   ├── stack-template/         ← project template
│   └── tools/                  ← misc tools
├── movie-scraper-tools/        ← media toolkit
│   ├── tools/
│   │   ├── torrent-finder/
│   │   ├── subtitle-finder/
│   │   ├── dubbed-finder/
│   │   └── media-info/
│   ├── tools.json
│   └── SKILL.md
├── scoute-research-framework/  ← research framework
│   ├── scout/
│   │   ├── orchestrator/
│   │   ├── phases/
│   │   ├── schemas/
│   │   └── tools/
│   ├── docs/
│   └── pyproject.toml
├── stack_inicial_proyectos/    ← Next.js template
│   └── front-end/nextjs/
├── reports_test/               ← research artifacts
├── Audits/                     ← audit reports
├── Codex/                      ← coding sub-agent logs
└── comandos_terminal/          ← cheatsheets

The layout is the result of iteration. The most important directories are .openclaw/ (framework state), devclaw-tools/ and movie-scraper-tools/ (the tool repos), and scoute-research-framework/ (the research framework).

Communication paths

The agents communicate through the following paths:

From	To	Path
Coordinator	Research Worker	HTTP POST to `127.0.0.1:18790/<endpoint>`
Coordinator	Media Agent	HTTP POST to `127.0.0.1:18790/<endpoint>`
Coordinator	Web Agent	In-process call to the browser tool
Coordinator	Coding Assistant	In-process call to the coding sub-agent
Research Worker	Coordinator	HTTP response (synchronous)
Media Agent	Coordinator	HTTP response (synchronous)
Web Agent	Coordinator	In-process return
Coding Assistant	Coordinator	In-process return
Research Worker	Research Framework	In-process call to the orchestrator
Coding Assistant	Coding sub-agent	CLI invocation (`codex exec ...`)
Research Framework	Adapters	In-process call to adapter functions
Adapters	External	HTTP / HTTPS to provider APIs

The paths are unidirectional where possible. The response path mirrors the request path.

Configuration files

The lab's configuration is spread across several files:

File	Purpose
`.openclaw/openclaw.json`	Main framework config (model, ports, paths).
`.openclaw/agents/main/agent/models.json`	The Coordinator's model config.
`.openclaw/agents/scout/agent/models.json`	The Scout's model config.
`{project}/tools.json`	The tool registry for a project.
`scoute-research-framework/config/*.json`	The research framework's adapter config.
`~/.codex/config.toml`	The coding sub-agent's config (sandbox, trust).
`~/Library/LaunchAgents/*.plist`	The launchd units (macOS).
`/etc/systemd/system/*.service`	The systemd units (Linux).

Configuration changes are made by the Coordinator and require explicit user authorization.

Deployment topology

The lab is a single-host deployment. All processes run on the user's machine. The only network access is to external providers (model, search, streaming).

Loading diagram…

Single-host deployment — two gateways, one coding sub-agent, one browser, one media server, plus external providers.

The host is the user's machine (typically a MacBook Pro on macOS). The host has:

A coordinator gateway on port 18789.
A Scout gateway on port 18790.
A coding sub-agent invoked on demand.
A browser (Chromium) on CDP port 18800.
A Media Lab Server on port 8765.

The host has network access to the model's provider (over HTTPS) and to the local network (mDNS for device discovery).

Failure domains

The lab's failure domains are:

Domain	What can fail
Coordinator gateway	All routing; the user is disconnected.
Scout gateway	Research and media; the user is partially disconnected.
Coding sub-agent	One invocation; retries handle transient failures.
Browser	The Web Agent; the Coordinator can restart the browser.
Media Lab Server	Generation; the Coordinator can restart the server.
Model provider	All model calls; the framework retries with backoff.
Search provider	One adapter; the framework falls back to another.
Streaming service	One source; the Media Agent tries the next source.
Device	Playback; the Media Agent surfaces the error.

The failure domains are designed to be small. A failure in one domain does not cascade to others.

Performance

The lab's performance is bounded by:

Model latency. The Coordinator's response time is dominated by the model provider's response time.
Adapter latency. The Research Framework's response time is dominated by the search adapters' response time.
Tool latency. The Coding Assistant's response time is dominated by the coding sub-agent's response time.

The lab does not aim for real-time response. It aims for bounded, predictable response. A typical request completes in 5-30 seconds; a research mission completes in 2-5 minutes.