# eth-ivia-lab/vacp architecture

> Architecture diagram of the GitHub repository eth-ivia-lab/vacp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eth-ivia-lab/vacp
- Repository: https://github.com/eth-ivia-lab/vacp

## Overview

VACP is an in-app protocol that lets AI agents inspect visual-analytics capabilities and state, then invoke semantic actions that update the interface. The repository supplies protocol/runtime primitives, visualization-provider adapters, agent transports, and debugging tools; it also includes a separate agent-evaluation suite. The graph emphasizes the documented agent-to-visualization workflow and sampled evaluation flow. Some provider and UI wiring is unsampled, so unsupported implementation-level connections are omitted.

Main entry points: [`packages/lib/evaluation/agent-arena/src/cli.ts`](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/cli.ts) (Arena CLI), [`packages/lib/protocol/gateway/src/runtime/create-runtime-bridge.ts`](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/protocol/gateway/src/runtime/create-runtime-bridge.ts) (Runtime Bridge), [`packages/lib/transports/mcp-server/src/vacp_mcp_server/main.py`](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/mcp-server/src/vacp_mcp_server/main.py) (MCP Server Entry), [`packages/lib/transports/mcp-server/src/vacp_mcp_server/server.py`](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/mcp-server/src/vacp_mcp_server/server.py) (MCP Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Protocol Runtime"]
  node_contract["Protocol Contract<br/>[schema.ts]"]
  node_runtime["Runtime Bridge"]
  node_domstate["DOM Snapshot<br/>[dom-snapshot.ts]"]
  node_duckdb["DuckDB Client<br/>[client.ts]"]
end

subgraph group_providers["Visualization Providers"]
  node_vegalite["Vega-Lite Adapter<br/>[duckdb-handle.ts]"]
  node_vgplot["vgplot Actions<br/>[actions.ts]"]
end

subgraph group_transports["Agent Transports"]
  node_agentclient["Agent Client"]
  node_mcpentry["MCP Server Entry<br/>[main.py]"]
  node_mcptools["MCP Tools<br/>[server.py]"]
  node_bridgeclient["Browser Bridge Client<br/>[bridge.py]"]
  node_browser["Browser Control<br/>[browser.py]"]
end

subgraph group_tooling["Developer Tooling"]
  node_debugui["Debug Overlay<br/>[debug-ui-view.tsx]"]
  node_analytics["Analytics Runtime<br/>[runtime.ts]"]
end

subgraph group_evaluation["Evaluation Suite"]
  node_arena["Arena CLI<br/>[cli.ts]"]
  node_runner["Scenario Runner<br/>[run.ts]"]
  node_sessionlogs["Session Export<br/>[export-session.ts]"]
  node_analysis["Run Analysis<br/>[analyze-run.ts]"]
  node_report["Report Generation<br/>[render-html.ts]"]
  node_plainmcp["Plain MCP Runtime<br/>[runtime.py]"]
end

node_agent(("AI Agent"))

node_agent -->|"uses contract"| node_contract
node_agent -->|"reads state"| node_runtime
node_agent -->|"executes actions"| node_runtime
node_runtime -->|"snapshots DOM"| node_domstate
node_vegalite -->|"uses queries"| node_duckdb
node_vgplot -->|"uses selection"| node_duckdb
node_mcpentry -->|"creates server"| node_mcptools
node_mcptools -->|"calls bridge"| node_bridgeclient
node_mcpentry -->|"controls browser"| node_browser
node_arena -->|"starts runs"| node_runner
node_arena -->|"exports sessions"| node_sessionlogs
node_arena -->|"analyzes runs"| node_analysis
node_analysis -.->|"feeds analysis"| node_report
node_plainmcp -->|"uses browser"| node_browser

click node_contract "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/protocol/core/src/schema.ts"
click node_runtime "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/protocol/gateway/src/runtime/create-runtime-bridge.ts"
click node_domstate "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/protocol/gateway/src/dom-snapshot.ts"
click node_duckdb "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/protocol/duckdb/src/client.ts"
click node_vegalite "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/providers/vega-lite/src/duckdb-handle.ts"
click node_vgplot "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/providers/vgplot/src/actions.ts"
click node_agentclient "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/agent-client/src/create-llm-model.ts"
click node_mcpentry "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/mcp-server/src/vacp_mcp_server/main.py"
click node_mcptools "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/mcp-server/src/vacp_mcp_server/server.py"
click node_bridgeclient "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/mcp-server/src/vacp_mcp_server/bridge.py"
click node_browser "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/mcp-server/src/vacp_mcp_server/browser.py"
click node_debugui "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/tooling/debug-ui/src/overlay/debug-ui-view.tsx"
click node_analytics "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/tooling/analytics/src/runtime.ts"
click node_arena "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/cli.ts"
click node_runner "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/runner/run.ts"
click node_sessionlogs "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/logs/export-session.ts"
click node_analysis "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/analyze/analyze-run.ts"
click node_report "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/report/render-html.ts"
click node_plainmcp "https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/plain-mcp/src/plain_mcp/runtime.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_contract,node_runtime,node_domstate,node_duckdb toneBlue
class node_vegalite,node_vgplot toneAmber
class node_agentclient,node_mcpentry,node_mcptools,node_bridgeclient,node_browser toneMint
class node_debugui,node_analytics toneRose
class node_arena,node_runner,node_sessionlogs,node_analysis,node_report,node_plainmcp,node_agent toneIndigo
```

## Components

### Protocol Runtime

- [Protocol Contract](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/protocol/core/src/schema.ts): `packages/lib/protocol/core/src/schema.ts`
- [Runtime Bridge](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/protocol/gateway/src/runtime/create-runtime-bridge.ts): `packages/lib/protocol/gateway/src/runtime/create-runtime-bridge.ts`
- [DOM Snapshot](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/protocol/gateway/src/dom-snapshot.ts): `packages/lib/protocol/gateway/src/dom-snapshot.ts`
- [DuckDB Client](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/protocol/duckdb/src/client.ts): `packages/lib/protocol/duckdb/src/client.ts`

### Visualization Providers

- [Vega-Lite Adapter](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/providers/vega-lite/src/duckdb-handle.ts): `packages/lib/providers/vega-lite/src/duckdb-handle.ts`
- [vgplot Actions](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/providers/vgplot/src/actions.ts): `packages/lib/providers/vgplot/src/actions.ts`

### Agent Transports

- [Agent Client](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/agent-client/src/create-llm-model.ts): `packages/lib/transports/agent-client/src/create-llm-model.ts`
- [MCP Server Entry](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/mcp-server/src/vacp_mcp_server/main.py): `packages/lib/transports/mcp-server/src/vacp_mcp_server/main.py`
- [MCP Tools](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/mcp-server/src/vacp_mcp_server/server.py): `packages/lib/transports/mcp-server/src/vacp_mcp_server/server.py`
- [Browser Bridge Client](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/mcp-server/src/vacp_mcp_server/bridge.py): `packages/lib/transports/mcp-server/src/vacp_mcp_server/bridge.py`
- [Browser Control](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/transports/mcp-server/src/vacp_mcp_server/browser.py): `packages/lib/transports/mcp-server/src/vacp_mcp_server/browser.py`

### Developer Tooling

- [Debug Overlay](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/tooling/debug-ui/src/overlay/debug-ui-view.tsx): `packages/lib/tooling/debug-ui/src/overlay/debug-ui-view.tsx`
- [Analytics Runtime](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/tooling/analytics/src/runtime.ts): `packages/lib/tooling/analytics/src/runtime.ts`

### Evaluation Suite

- [Arena CLI](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/cli.ts): `packages/lib/evaluation/agent-arena/src/cli.ts`
- [Scenario Runner](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/runner/run.ts): `packages/lib/evaluation/agent-arena/src/runner/run.ts`
- [Session Export](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/logs/export-session.ts): `packages/lib/evaluation/agent-arena/src/logs/export-session.ts`
- [Run Analysis](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/analyze/analyze-run.ts): `packages/lib/evaluation/agent-arena/src/analyze/analyze-run.ts`
- [Report Generation](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/agent-arena/src/report/render-html.ts): `packages/lib/evaluation/agent-arena/src/report/render-html.ts`
- [Plain MCP Runtime](https://github.com/eth-ivia-lab/vacp/blob/main/packages/lib/evaluation/plain-mcp/src/plain_mcp/runtime.py): `packages/lib/evaluation/plain-mcp/src/plain_mcp/runtime.py`

### Other components

- **AI Agent**

## Connections

- AI Agent → Protocol Contract: uses contract (evidence: `README.md`)
- AI Agent → Runtime Bridge: reads state (evidence: `README.md`)
- AI Agent → Runtime Bridge: executes actions (evidence: `README.md`)
- Runtime Bridge → DOM Snapshot: snapshots DOM (evidence: `packages/lib/protocol/gateway/src/dom-snapshot.ts`)
- Vega-Lite Adapter → DuckDB Client: uses queries (evidence: `packages/lib/providers/vega-lite/src/duckdb-handle.ts`)
- vgplot Actions → DuckDB Client: uses selection (evidence: `packages/lib/providers/vgplot/src/actions.ts`)
- MCP Server Entry → MCP Tools: creates server (evidence: `packages/lib/transports/mcp-server/src/vacp_mcp_server/main.py`)
- MCP Tools → Browser Bridge Client: calls bridge (evidence: `packages/lib/transports/mcp-server/src/vacp_mcp_server/server.py`)
- MCP Server Entry → Browser Control: controls browser (evidence: `packages/lib/transports/mcp-server/src/vacp_mcp_server/main.py`)
- Arena CLI → Scenario Runner: starts runs (evidence: `packages/lib/evaluation/agent-arena/src/cli.ts`)
- Arena CLI → Session Export: exports sessions (evidence: `packages/lib/evaluation/agent-arena/src/cli.ts`)
- Arena CLI → Run Analysis: analyzes runs (evidence: `packages/lib/evaluation/agent-arena/src/cli.ts`)
- Run Analysis → Report Generation: feeds analysis
- Plain MCP Runtime → Browser Control: uses browser (evidence: `packages/lib/evaluation/plain-mcp/src/plain_mcp/main.py`)
