⚡ Web MCP Standard Interface

This documentation natively implements the Web Model Context Protocol (Web MCP) for internal and local AI agents. Every section exposes semantic HTML attributes (tool-name, description, tool-param-*) allowing autonomous AI agents to inspect, invoke, and retrieve structured context directly from DOM queries without external wrappers.

🔒 Governance Notice: Strictly Private & Local Environment. External publication or deployment is forbidden without a dedicated Landing page and formal completion of the canonical INBOX protocol.

read_architecture_spec Returns system topology, Docker services, and network layout.

get_deployment_guide Returns step-by-step production deployment commands.

get_configuration_reference Inspects environment variables, persistent volumes, and OBS config.

get_security_directives Audits socket removal, credential hygiene, and IP spoofing defenses.

get_adr_0001 Reads Architectural Decision Record on Docker containerization.

search_documentation Executes keyword search across all documentation sections.

⚡ Web MCP Interactive Tool Runner

READY

1. System Architecture & Clean Design SPEC

ApliArte Directo is built on the principles of clean architecture, minimal resource footprint, strict service decoupling, and security by design. It decouples the broadcast rendering layer from the ingest streamer, enabling reliable live streaming directly to Twitch without heavy OBS host instances.

2. Service Topology Diagram

                           [ INTERNET / USERS ]
                                      │
            ┌─────────────────────────┴─────────────────────────┐
            │                                                   │
    [ Ports 80 / 443 ]                                  [ Port 7979 ]
 (Optional: Profile ssl)                            (Direct Access / Proxy)
            ▼                                                   ▼
┌───────────────────────┐                           ┌───────────────────────┐
│     caddy (proxy)     │──────────(HTTP)──────────>│    overlay (Node 22)  │
│  (Caddy 2 Auto SSL)   │                           │ - Three.js 3 Diorama  │
└───────────────────────┘                           │ - Twitch Chat (IRC)   │
                                                    │ - Digital Audio Relay │
                                                    │ - Mobile Cockpit UI   │
                                                    │ - Layer Persistence   │
                                                    └───────────┬───────────┘
                                                                │
                                            Private Bridge Network: directo-network
                                            (Internal HTTP Requests :3000)
                                                                │
                                                                ▼
                                                    ┌───────────────────────┐
                                                    │      whip (Node/Web)  │
                                                    │ - Headless Chromium   │
                                                    │ - VDO.ninja WebRTC    │
                                                    │ - WHIP Push to Twitch │
                                                    │ - Internal Control API│
                                                    └───────────┬───────────┘
                                                                │ (WHIP WebRTC)
                                                                ▼
                                                        [ TWITCH INGEST ]

3. Docker Compose Services

overlay (Node 22 Alpine): Serves the real-time 3D diorama (Three.js), avatars, Twitch IRC listener, mini-games (!traidor), mobile audio PCM relay, and the cockpit control dashboard on port 7979.
whip (Debian Bookworm / Chromium Headless): Loads the VDO.ninja audio/video mixer and broadcasts via WHIP (WebRTC HTTP Ingestion Protocol) directly to Twitch. Consumes only 300–500 MB RAM. Exposes an internal HTTP control plane on port 3000.
caddy (Caddy 2 Alpine): Optional reverse proxy with automated ACME Let's Encrypt TLS certificate provisioning, active under profiles: ["ssl"].

4. WHIP Headless WebRTC Streamer

WHIP eliminates the legacy dependency on Xvfb, PulseAudio virtual sinks, and FFmpeg software transcoding. Chromium sends encoded H.264/AAC WebRTC streams directly to Twitch Ingest points, resulting in zero generation loss and drastically lower CPU/RAM consumption.

5. Internal Control API (Port 3000)

Accessible strictly inside the private Docker bridge network (never exposed to host or internet):

Method	Endpoint	Access	Description
`GET`	`http://whip:3000/status`	Internal Docker	Returns current broadcast state: `{ ok: true, streaming: boolean }`
`POST`	`http://whip:3000/start`	Internal Docker	Launches headless browser capture and initiates Twitch broadcast.
`POST`	`http://whip:3000/stop`	Internal Docker	Terminates the live broadcast and frees browser memory.

6. Configuration Reference Manual CONFIG

Configuration is managed via environment variables (.env) and persistent Docker host volumes.

Variable	Type	Default	Required	Description
`PANEL_PASS`	String	(Empty)	YES	Master password to authenticate in the mobile cockpit and control API.
`TWITCH_STREAM_KEY`	String	(Empty)	YES (to stream)	Twitch broadcast ingestion key (`live_...`).
`VDO_ROOM`	String	`erbolammapliarte`	No	VDO.ninja room name where video feeds and guest cameras assemble.
`VDO_PASS`	String	(vacía)	No	Password for the VDO.ninja mixer room.
`OVERLAY_PORT`	Number	`7979`	No	Host port mapped to the overlay HTTP/WebSocket server.
`AUTO_START`	Boolean	`false`	No	When `true`, automatically starts Twitch streaming upon container boot.
`DOMAIN`	String	(Empty)	Required for SSL	Public domain name (e.g. `directo.mydomain.com`) used by Caddy.

Storage Directories & Persistent Volumes

./data:/app/data: Stores layers.json (layer visibility and ordering), categoria.json (stream topic), and camara.json.
./medios:/app/medios: Media directory containing sound effects (.mp3, .wav), overlay banners, and visual stings.

7. Production Deployment Guide DEPLOY

Deployment is fully containerized. A single Docker Compose command spins up the entire production stack.

Standard VPS Deployment (Behind existing reverse proxy)

# 1. Clone the repository
git clone https://github.com/erbolamm/apliarte-directo.git /opt/apliarte-directo
cd /opt/apliarte-directo

# 2. Configure environment credentials
cp .env.example .env
nano .env

# 3. Launch the container stack in detached mode
docker compose up -d

# 4. Verify service health
docker compose ps
docker compose logs -f overlay

Autonomous Deployment with Automated Let's Encrypt SSL

# Enable Caddy SSL reverse proxy profile
docker compose --profile ssl up -d

Zero-Downtime Hot Upgrades

# Pull latest source updates and recreate modified containers
git pull origin main
docker compose build overlay
docker compose up -d --no-deps overlay

8. Defensive Security Directives SECURITY

1. Complete Elimination of the Docker Socket

Legacy architectures frequently mounted /var/run/docker.sock into web containers to allow the web server to start and stop auxiliary streaming containers. This granted root-equivalent privileges on the host machine.

ApliArte Directo solves this cleanly: the overlay container communicates with the whip container exclusively via the internal HTTP control plane on port 3000 over an isolated bridge network. The Docker socket is completely omitted.

2. Reverse Proxy IP Spoofing Prevention

The server enforces strict isKnownTrustedProxy(ip) validation before trusting forwarded client headers (x-forwarded-for, x-real-ip). If a client connects directly to the server and attempts to forge internal IP addresses (e.g. 127.0.0.1), the header is discarded and the real TCP socket IP is recorded.

3. Credential Enforcement

In production (NODE_ENV=production), server.js verifies that PANEL_PASS is securely defined. If empty or left at a known default, the process immediately halts with an exit code of 1.

9. ADR-0001: Architectural Decoupling & Docker Stack ADR

Status: ACCEPTED (2026-09-27)

Context: Live broadcast components were historically coupled inside the central orchestration repository, complicating modular maintenance and automated testing.

Decision: Decouple the direct broadcast stack into an autonomous, strictly private repository (apliarte-directo), containerize all services using Docker Compose, eliminate the Docker daemon socket mount, and provide local Web MCP semantic documentation. All assets and services remain 100% private and local; public publication requires a dedicated Landing page and formal completion of the INBOX protocol.

Consequences: Zero host privileges required for containers, RAM consumption reduced by over 70%, independent versioning, and instant local execution with Docker.