Appendix E: Reference Architecture

Un único diagrama anotado grande de la architecture del lab con todos los components, ports, paths y communication flows. La única página para imprimir.

Propósito

Este appendix es el único diagrama anotado de la architecture del lab. Complementa la página System Architecture con una vista única, grande e imprimible.

El diagrama está sanitized: real names, real paths y real agent identifiers se reemplazan con placeholders. Los lugares donde van los placeholders se marcan con {...}.

The diagram

Loading diagram…

Haz clic en cualquier caja para abrir su página de documentación.

Annotated components

External services

Component	Protocol	Purpose
Model Provider A	HTTPS	El primary model del Coordinator.
Model Provider B	HTTPS	La fast variant del Coordinator.
Search Provider: Tavily	HTTPS	El primary search adapter del research framework.
Search Provider: DuckDuckGo	HTTPS	El fallback search adapter.
Search Provider: Google	HTTPS	El optional Google Custom Search adapter.
Video: YouTube	HTTPS	YouTube search y transcript.
Streaming: Stremio	mDNS	Stremio catalog y streaming.
Chromecast Devices	mDNS	Cast-capable displays en la LAN.
VLC Hosts on LAN	mDNS	Instancias de VLC con RC/HTTP enabled.

Gateway layer

Component	Port	Purpose
Coordinator	18789	El main gateway. El entry point del usuario.
Scout	18790	El specialized gateway para el Research Worker y el Media Agent.

Agent layer

Component	Purpose
Coordinator	Routea requests, maneja memory y sessions, activa skills.
Coding Assistant	Revisa código del sub-agent, integra, testea.
Research Worker	Corre research missions end-to-end.
Media Agent	Maneja media search y playback a local y remote devices.
Web Agent	Maneja el browser a través del accessibility tree.

Framework layer

Component	Purpose
Research Framework	Orchestra las 8 phases; maneja artifacts, state y el request journal.
Coding Sub-agent	El Codex CLI sandboxed al que delega el Coding Assistant.

Tool layer

Component	Purpose
CLI tools	Las deterministic CLI tools del lab (torrent-finder, etc.).
chromecast	Descubre y controla Cast devices.
vlc	Spawnea y controla VLC local y remote.
media-playback	Selecciona el right backend para una source dada.
media-lab-server	Genera imágenes y music a través de una HTTP API.
browser	Maneja un browser Chromium-based.

Adapter layer

Component	Purpose
tavily	Search adapter para Tavily.
duckduckgo	Search adapter para DuckDuckGo.
google_search	Search adapter para Google Custom Search.
youtube_transcript	Transcript adapter para YouTube.
yt-dlp	Fallback video metadata adapter.
perplexity	Synthesis adapter con un token pool.

State layer

Component	Purpose
MEMORY.md	La long-term memory del lab.
Daily logs	El raw chronological record.
Session state	El in-memory state de la current session.
Skills	Las capabilities del agent (SKILL.md, TOOL.md).
Mission artifacts	Los typed outputs del research framework.
Request journal	El append-only log de external calls.
Token pool state	El live state del token pool.
Audit reports	Los weekly, monthly, quarterly y ad-hoc audits.

How to read the diagram

User es la única external entity. El user se comunica con el Coordinator a través del Coordinator gateway.
Coordinator gateway es el entry point. El Coordinator en sí corre dentro del gateway process.
Scout gateway hostea el Research Worker y el Media Agent. El Coordinator habla con el Scout por HTTP.
Coding sub-agent lo invoca el Coding Assistant. El sub-agent corre en un sandbox.
Web Agent maneja el browser a través de la OpenClaw browser tool en el CDP port.
Media Lab Server es un standalone HTTP server (:8765) que el Coordinator puede llamar directamente.
State layer es el foundation. Cada otra layer lee y escribe en la state layer.

What the diagram does not show

Per-process supervision (launchd, systemd).
Configuration file locations (ver Environment Variables).
Specific commands (ver el Runbook).
Failure modes (ver Failure Catalog).

El diagrama es una única vista del sistema. Los details están en las otras páginas.