# dcode-v05/browser-agent architecture

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

- Interactive diagram: https://gitdiagram.com/dcode-v05/browser-agent
- Repository: https://github.com/dcode-v05/browser-agent

## Overview

bap-browser lets an AI agent operate a browser through MCP tools while a person watches and can intervene in a live viewer. The main flow is task input → agent/model → browser tools → policy-checked browser session; the service streams activity to the viewer and routes human controls back to the session. The graph also shows configuration, safety policy, and the viewer’s event-driven state/UI. Some links rely on README statements or SOURCE INDEX references because the relevant source was not excerpted.

Main entry points: [`viewer/src/App.tsx`](https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/App.tsx) (Viewer application), [`src/bap_browser/driver/session.py`](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/driver/session.py) (Browser session), [`src/bap_browser/agent/command.py`](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/agent/command.py) (Task input), [`src/bap_browser/agent/loop.py`](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/agent/loop.py) (Agent loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_task["Task input<br/>[command.py]"]
  node_mcp["MCP server<br/>[server.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_agent["Agent and tools"]
  node_agent_loop["Agent loop<br/>[loop.py]"]
  node_agent_models["Agent models<br/>[models.py]"]
  node_openai_model["OpenAI adapter<br/>[openai_model.py]"]
  node_toolkit["Tool toolkit<br/>[toolkit.py]"]
  node_browser_tools["Browser tools<br/>[browser_tools.py]"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_sentences["Tool descriptions<br/>[sentences.py]"]
end

subgraph group_browser["Browser and safety"]
  node_browser_session["Browser session<br/>[session.py]"]
  node_playwright["Playwright driver"]
  node_driver_base["Driver interface<br/>[base.py]"]
  node_url_policy["URL policy<br/>[url_policy.py]"]
  node_address["Address normalization<br/>[address.py]"]
  node_redaction["Redaction<br/>[redaction.py]"]
end

subgraph group_service["Session service"]
  node_service_session["Service session<br/>[session.py]"]
  node_service_app["HTTP and WebSocket<br/>[app.py]"]
  node_service_server["Service runtime<br/>[server.py]"]
  node_events["Event hub<br/>[events.py]"]
end

subgraph group_viewer["Human viewer"]
  node_viewer_app["Viewer application<br/>[App.tsx]"]
  node_viewer_protocol["Viewer protocol<br/>[protocol.ts]"]
  node_viewer_socket["WebSocket connection<br/>[socket.ts]"]
  node_viewer_state["Viewer state<br/>[reducer.ts]"]
  node_browser_pane["Browser pane<br/>[BrowserPane.tsx]"]
  node_settings["Settings screen<br/>[SettingsScreen.tsx]"]
  node_status["Status panel<br/>[StatusPanel.tsx]"]
  node_timeline["Activity timeline<br/>[Timeline.tsx]"]
  node_viewer_ui["Viewer components<br/>[ChatPanel.tsx]"]
end

node_person(("Person"))
node_model_service["OpenAI model"]

node_person -->|"submits task"| node_task
node_task -->|"starts run"| node_agent_loop
node_agent_loop -->|"uses model types"| node_agent_models
node_agent_loop -->|"offers tools"| node_toolkit
node_openai_model -->|"requests completion"| node_model_service
node_agent_loop -.->|"uses model adapter"| node_openai_model
node_toolkit -.->|"registers tools"| node_browser_tools
node_browser_tools -->|"operates browser"| node_browser_session
node_browser_tools -->|"uses registry"| node_registry
node_sentences -->|"describes tools"| node_registry
node_mcp -->|"exposes tools"| node_toolkit
node_mcp -.->|"creates driver session"| node_browser_session
node_task -->|"starts service"| node_service_server
node_task -->|"starts session"| node_service_session
node_service_session -->|"owns browser"| node_browser_session
node_browser_session -->|"starts driver"| node_playwright
node_playwright -->|"implements interface"| node_driver_base
node_browser_session -->|"checks addresses"| node_url_policy
node_browser_session -->|"redacts output"| node_redaction
node_url_policy -.->|"normalizes URLs"| node_address
node_service_session -->|"publishes activity"| node_events
node_service_server -->|"hosts app"| node_service_app
node_service_app -->|"routes viewer commands"| node_service_session
node_service_app -.->|"streams events"| node_events
node_config -->|"configures browser"| node_browser_session
node_config -->|"configures service"| node_service_server
node_service_server -->|"provides viewer address"| node_person
node_person -->|"watches and controls"| node_viewer_app
node_viewer_app -->|"creates connection"| node_viewer_socket
node_viewer_socket -->|"dispatches events"| node_viewer_state
node_viewer_socket -.->|"exchanges events and commands"| node_service_app
node_viewer_protocol -->|"defines messages"| node_viewer_socket
node_viewer_app -->|"reduces events"| node_viewer_state
node_viewer_app -->|"renders browser"| node_browser_pane
node_viewer_app -->|"renders settings"| node_settings
node_viewer_app -->|"renders status"| node_status
node_viewer_app -->|"renders activity"| node_timeline
node_viewer_app -->|"renders chat"| node_viewer_ui
node_viewer_app -->|"uses message types"| node_viewer_protocol

click node_task "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/agent/command.py"
click node_mcp "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/mcp/server.py"
click node_config "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/config.py"
click node_agent_loop "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/agent/loop.py"
click node_agent_models "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/agent/models.py"
click node_openai_model "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/agent/openai_model.py"
click node_toolkit "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/tools/toolkit.py"
click node_browser_tools "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/tools/browser_tools.py"
click node_registry "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/tools/registry.py"
click node_sentences "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/tools/sentences.py"
click node_service_session "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/service/session.py"
click node_browser_session "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/driver/session.py"
click node_playwright "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/driver/playwright_driver.py"
click node_driver_base "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/driver/base.py"
click node_url_policy "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/policy/url_policy.py"
click node_address "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/policy/address.py"
click node_redaction "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/policy/redaction.py"
click node_service_app "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/service/app.py"
click node_service_server "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/service/server.py"
click node_events "https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/service/events.py"
click node_viewer_app "https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/App.tsx"
click node_viewer_protocol "https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/protocol.ts"
click node_viewer_socket "https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/connection/socket.ts"
click node_viewer_state "https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/state/reducer.ts"
click node_browser_pane "https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/components/BrowserPane.tsx"
click node_settings "https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/components/SettingsScreen.tsx"
click node_status "https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/components/StatusPanel.tsx"
click node_timeline "https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/components/Timeline.tsx"
click node_viewer_ui "https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/components/ChatPanel.tsx"

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_task,node_mcp,node_config toneBlue
class node_agent_loop,node_agent_models,node_openai_model,node_toolkit,node_browser_tools,node_registry,node_sentences toneAmber
class node_browser_session,node_playwright,node_driver_base,node_url_policy,node_address,node_redaction toneMint
class node_service_session,node_service_app,node_service_server,node_events toneRose
class node_viewer_app,node_viewer_protocol,node_viewer_socket,node_viewer_state,node_browser_pane,node_settings,node_status,node_timeline,node_viewer_ui,node_person,node_model_service toneIndigo
```

## Components

### Entry points

- [Task input](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/agent/command.py): `src/bap_browser/agent/command.py`
- [MCP server](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/mcp/server.py): `src/bap_browser/mcp/server.py`
- [Configuration](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/config.py): `src/bap_browser/config.py`

### Agent and tools

- [Agent loop](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/agent/loop.py): `src/bap_browser/agent/loop.py`
- [Agent models](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/agent/models.py): `src/bap_browser/agent/models.py`
- [OpenAI adapter](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/agent/openai_model.py): `src/bap_browser/agent/openai_model.py`
- [Tool toolkit](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/tools/toolkit.py): `src/bap_browser/tools/toolkit.py`
- [Browser tools](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/tools/browser_tools.py): `src/bap_browser/tools/browser_tools.py`
- [Tool registry](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/tools/registry.py): `src/bap_browser/tools/registry.py`
- [Tool descriptions](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/tools/sentences.py): `src/bap_browser/tools/sentences.py`

### Browser and safety

- [Browser session](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/driver/session.py): `src/bap_browser/driver/session.py`
- [Playwright driver](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/driver/playwright_driver.py): `src/bap_browser/driver/playwright_driver.py`
- [Driver interface](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/driver/base.py): `src/bap_browser/driver/base.py`
- [URL policy](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/policy/url_policy.py): `src/bap_browser/policy/url_policy.py`
- [Address normalization](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/policy/address.py): `src/bap_browser/policy/address.py`
- [Redaction](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/policy/redaction.py): `src/bap_browser/policy/redaction.py`

### Session service

- [Service session](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/service/session.py): `src/bap_browser/service/session.py`
- [HTTP and WebSocket](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/service/app.py): `src/bap_browser/service/app.py`
- [Service runtime](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/service/server.py): `src/bap_browser/service/server.py`
- [Event hub](https://github.com/dcode-v05/browser-agent/blob/main/src/bap_browser/service/events.py): `src/bap_browser/service/events.py`

### Human viewer

- [Viewer application](https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/App.tsx): `viewer/src/App.tsx`
- [Viewer protocol](https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/protocol.ts): `viewer/src/protocol.ts`
- [WebSocket connection](https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/connection/socket.ts): `viewer/src/connection/socket.ts`
- [Viewer state](https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/state/reducer.ts): `viewer/src/state/reducer.ts`
- [Browser pane](https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/components/BrowserPane.tsx): `viewer/src/components/BrowserPane.tsx`
- [Settings screen](https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/components/SettingsScreen.tsx): `viewer/src/components/SettingsScreen.tsx`
- [Status panel](https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/components/StatusPanel.tsx): `viewer/src/components/StatusPanel.tsx`
- [Activity timeline](https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/components/Timeline.tsx): `viewer/src/components/Timeline.tsx`
- [Viewer components](https://github.com/dcode-v05/browser-agent/blob/main/viewer/src/components/ChatPanel.tsx): `viewer/src/components/ChatPanel.tsx`

### Other components

- **Person**
- **OpenAI model**

## Connections

- Person → Task input: submits task
- Task input → Agent loop: starts run (evidence: `src/bap_browser/agent/command.py`)
- Agent loop → Agent models: uses model types (evidence: `src/bap_browser/agent/loop.py`)
- Agent loop → Tool toolkit: offers tools (evidence: `src/bap_browser/agent/loop.py`)
- OpenAI adapter → OpenAI model: requests completion (evidence: `src/bap_browser/agent/openai_model.py`)
- Agent loop → OpenAI adapter: uses model adapter
- Tool toolkit → Browser tools: registers tools
- Browser tools → Browser session: operates browser (evidence: `src/bap_browser/tools/browser_tools.py`)
- Browser tools → Tool registry: uses registry (evidence: `src/bap_browser/tools/browser_tools.py`)
- Tool descriptions → Tool registry: describes tools (evidence: `src/bap_browser/tools/sentences.py`)
- MCP server → Tool toolkit: exposes tools (evidence: `src/bap_browser/mcp/server.py`)
- MCP server → Browser session: creates driver session
- Task input → Service runtime: starts service (evidence: `src/bap_browser/agent/command.py`)
- Task input → Service session: starts session (evidence: `src/bap_browser/agent/command.py`)
- Service session → Browser session: owns browser (evidence: `src/bap_browser/service/session.py`)
- Browser session → Playwright driver: starts driver (evidence: `src/bap_browser/driver/session.py`)
- Playwright driver → Driver interface: implements interface (evidence: `src/bap_browser/driver/playwright_driver.py`)
- Browser session → URL policy: checks addresses (evidence: `src/bap_browser/driver/session.py`)
- Browser session → Redaction: redacts output (evidence: `src/bap_browser/driver/session.py`)
- URL policy → Address normalization: normalizes URLs
- Service session → Event hub: publishes activity (evidence: `src/bap_browser/service/session.py`)
- Service runtime → HTTP and WebSocket: hosts app (evidence: `src/bap_browser/service/server.py`)
- HTTP and WebSocket → Service session: routes viewer commands (evidence: `src/bap_browser/service/app.py`)
- HTTP and WebSocket → Event hub: streams events (evidence: `src/bap_browser/service/app.py`)
- Configuration → Browser session: configures browser (evidence: `src/bap_browser/driver/session.py`)
- Configuration → Service runtime: configures service (evidence: `src/bap_browser/service/server.py`)
- Service runtime → Person: provides viewer address (evidence: `src/bap_browser/service/server.py`)
- Person → Viewer application: watches and controls
- Viewer application → WebSocket connection: creates connection (evidence: `viewer/src/App.tsx`)
- WebSocket connection → Viewer state: dispatches events
- WebSocket connection → HTTP and WebSocket: exchanges events and commands
- Viewer protocol → WebSocket connection: defines messages (evidence: `viewer/src/connection/socket.ts`)
- Viewer application → Viewer state: reduces events (evidence: `viewer/src/App.tsx`)
- Viewer application → Browser pane: renders browser (evidence: `viewer/src/App.tsx`)
- Viewer application → Settings screen: renders settings (evidence: `viewer/src/App.tsx`)
- Viewer application → Status panel: renders status (evidence: `viewer/src/App.tsx`)
- Viewer application → Activity timeline: renders activity (evidence: `viewer/src/App.tsx`)
- Viewer application → Viewer components: renders chat (evidence: `viewer/src/App.tsx`)
- Viewer application → Viewer protocol: uses message types (evidence: `viewer/src/App.tsx`)
