# webbrain-one/webbrain architecture

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

- Interactive diagram: https://gitdiagram.com/webbrain-one/webbrain
- Repository: https://github.com/webbrain-one/webbrain

## Overview

WebBrain is an AI browser-agent extension: a user asks or delegates from the side panel; the agent reads the current page, optionally plans, invokes browser tools under Ask/Act/Dev permissions, and returns a result using a selected local or cloud model. It also supports reusable workflows, scheduled/watch tasks, offline emergency and retrieval resources, and external MCP/LM Studio delegation. The README establishes the product workflow and capabilities; source excerpts and the index support selected implementation links, while unsampled subsystems are represented without speculative call edges.

Main entry points: [`src/chrome/src/agent/agent.js`](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/agent.js) (Agent loop), [`src/chrome/src/ui/sidepanel.js`](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/ui/sidepanel.js) (Side panel), [`src/chrome/src/agent/offline-rag-worker.js`](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/offline-rag-worker.js) (Index worker), [`lmstudio-plugin/src/index.ts`](https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/src/index.ts) (LM Studio plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser experience"]
  node_panel["Side panel<br/>[sidepanel.js]"]
  node_page["Page access"]
end

subgraph group_agent["Agent execution"]
  node_agent["Agent loop<br/>[agent.js]"]
  node_planner["Task planning<br/>[planner.js]"]
  node_tools["Browser tools<br/>[tools.js]"]
  node_workflow["Saved workflows<br/>[workflows.js]"]
  node_scheduler["Scheduled watches<br/>[scheduler.js]"]
end

subgraph group_models["Model connections"]
  node_providers["Provider manager<br/>[manager.js]"]
  node_provider_impl["Model providers<br/>[openai.js]"]
  node_firefox_provider["Firefox OpenAI<br/>[openai.js]"]
end

subgraph group_offline["Offline knowledge"]
  node_offline_rag["Offline retrieval<br/>[offline-rag.js]"]
  node_offline_index["Offline index"]
  node_offline_worker["Index worker"]
  node_emergency_corpus[("Emergency corpus")]
  node_emergency_mode["Emergency mode<br/>[apocalypse-mode.js]"]
  node_download_control["Resource downloads"]
end

subgraph group_integrations["External delegation"]
  node_mcp_client(("MCP client"))
  node_mcp_server["MCP server<br/>[index.ts]"]
  node_bridge["Browser bridge<br/>[bridge.ts]"]
  node_lm_plugin["LM Studio plugin<br/>[index.ts]"]
  node_bridge_client["Bridge client<br/>[bridgeClient.ts]"]
  node_fetch_tools["URL research tools<br/>[researchUrl.ts]"]
end

node_user(("Browser user"))
node_lm_user(("LM Studio user"))

node_user -->|"asks or delegates"| node_panel
node_panel -.->|"starts tasks"| node_agent
node_agent -->|"reads page"| node_page
node_agent -->|"plans tasks"| node_planner
node_agent -->|"invokes tools"| node_tools
node_agent -.->|"generates with"| node_providers
node_providers -->|"dispatches to"| node_provider_impl
node_panel -->|"saves runs as"| node_workflow
node_panel -->|"schedules watches"| node_scheduler
node_agent -.->|"retrieves locally"| node_offline_rag
node_offline_worker -->|"builds passages for"| node_offline_rag
node_offline_worker -->|"parses vector index"| node_offline_index
node_offline_worker -->|"reads corpus files"| node_emergency_corpus
node_download_control -->|"uses store"| node_emergency_mode
node_download_control -->|"manages corpus"| node_emergency_corpus
node_mcp_client -->|"delegates browser task"| node_mcp_server
node_mcp_server -->|"starts and awaits runs"| node_bridge
node_bridge -.->|"commands browser"| node_agent
node_lm_user -->|"uses tools"| node_lm_plugin
node_lm_plugin -->|"calls research tools"| node_fetch_tools
node_lm_plugin -->|"delegates browser tasks"| node_bridge_client
node_bridge_client -.->|"sends browser commands"| node_agent

click node_panel "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/ui/sidepanel.js"
click node_page "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/content/accessibility-tree.js"
click node_agent "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/agent.js"
click node_planner "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/planner.js"
click node_tools "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/tools.js"
click node_workflow "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/workflows.js"
click node_scheduler "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/scheduler.js"
click node_providers "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/providers/manager.js"
click node_provider_impl "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/providers/openai.js"
click node_firefox_provider "https://github.com/webbrain-one/webbrain/blob/main/src/firefox/src/providers/openai.js"
click node_offline_rag "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/offline-rag.js"
click node_offline_index "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/offline-rag-index.js"
click node_offline_worker "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/offline-rag-worker.js"
click node_emergency_corpus "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/emergency-corpus.js"
click node_emergency_mode "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/apocalypse-mode.js"
click node_download_control "https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/emergency-download-controller.js"
click node_mcp_server "https://github.com/webbrain-one/webbrain/blob/main/mcp-server/src/index.ts"
click node_bridge "https://github.com/webbrain-one/webbrain/blob/main/mcp-server/src/bridge.ts"
click node_lm_plugin "https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/src/index.ts"
click node_bridge_client "https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/src/util/bridgeClient.ts"
click node_fetch_tools "https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/src/tools/researchUrl.ts"

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_panel,node_page,node_user,node_lm_user toneBlue
class node_agent,node_planner,node_tools,node_workflow,node_scheduler toneAmber
class node_providers,node_provider_impl,node_firefox_provider toneMint
class node_offline_rag,node_offline_index,node_offline_worker,node_emergency_corpus,node_emergency_mode,node_download_control toneRose
class node_mcp_client,node_mcp_server,node_bridge,node_lm_plugin,node_bridge_client,node_fetch_tools toneIndigo
```

## Components

### Browser experience

- [Side panel](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/ui/sidepanel.js): `src/chrome/src/ui/sidepanel.js`
- [Page access](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/content/accessibility-tree.js): `src/chrome/src/content/accessibility-tree.js`

### Agent execution

- [Agent loop](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/agent.js): `src/chrome/src/agent/agent.js`
- [Task planning](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/planner.js): `src/chrome/src/agent/planner.js`
- [Browser tools](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/tools.js): `src/chrome/src/agent/tools.js`
- [Saved workflows](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/workflows.js): `src/chrome/src/agent/workflows.js`
- [Scheduled watches](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/scheduler.js): `src/chrome/src/agent/scheduler.js`

### Model connections

- [Provider manager](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/providers/manager.js): `src/chrome/src/providers/manager.js`
- [Model providers](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/providers/openai.js): `src/chrome/src/providers/openai.js`
- [Firefox OpenAI](https://github.com/webbrain-one/webbrain/blob/main/src/firefox/src/providers/openai.js): `src/firefox/src/providers/openai.js`

### Offline knowledge

- [Offline retrieval](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/offline-rag.js): `src/chrome/src/agent/offline-rag.js`
- [Offline index](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/offline-rag-index.js): `src/chrome/src/agent/offline-rag-index.js`
- [Index worker](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/offline-rag-worker.js): `src/chrome/src/agent/offline-rag-worker.js`
- [Emergency corpus](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/emergency-corpus.js): `src/chrome/src/agent/emergency-corpus.js`
- [Emergency mode](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/apocalypse-mode.js): `src/chrome/src/agent/apocalypse-mode.js`
- [Resource downloads](https://github.com/webbrain-one/webbrain/blob/main/src/chrome/src/agent/emergency-download-controller.js): `src/chrome/src/agent/emergency-download-controller.js`

### External delegation

- **MCP client**
- [MCP server](https://github.com/webbrain-one/webbrain/blob/main/mcp-server/src/index.ts): `mcp-server/src/index.ts`
- [Browser bridge](https://github.com/webbrain-one/webbrain/blob/main/mcp-server/src/bridge.ts): `mcp-server/src/bridge.ts`
- [LM Studio plugin](https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/src/index.ts): `lmstudio-plugin/src/index.ts`
- [Bridge client](https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/src/util/bridgeClient.ts): `lmstudio-plugin/src/util/bridgeClient.ts`
- [URL research tools](https://github.com/webbrain-one/webbrain/blob/main/lmstudio-plugin/src/tools/researchUrl.ts): `lmstudio-plugin/src/tools/researchUrl.ts`

### Other components

- **Browser user**
- **LM Studio user**

## Connections

- Browser user → Side panel: asks or delegates (evidence: `README.md`)
- Side panel → Agent loop: starts tasks
- Agent loop → Page access: reads page (evidence: `README.md`)
- Agent loop → Task planning: plans tasks (evidence: `README.md`)
- Agent loop → Browser tools: invokes tools (evidence: `README.md`)
- Agent loop → Provider manager: generates with
- Provider manager → Model providers: dispatches to (evidence: `src/chrome/src/providers/manager.js`)
- Side panel → Saved workflows: saves runs as (evidence: `README.md`)
- Side panel → Scheduled watches: schedules watches (evidence: `README.md`)
- Agent loop → Offline retrieval: retrieves locally
- Index worker → Offline retrieval: builds passages for (evidence: `src/chrome/src/agent/offline-rag-worker.js`)
- Index worker → Offline index: parses vector index (evidence: `src/chrome/src/agent/offline-rag-worker.js`)
- Index worker → Emergency corpus: reads corpus files (evidence: `src/chrome/src/agent/offline-rag-worker.js`)
- Resource downloads → Emergency mode: uses store (evidence: `src/chrome/src/agent/emergency-download-controller.js`)
- Resource downloads → Emergency corpus: manages corpus (evidence: `src/chrome/src/agent/emergency-download-controller.js`)
- MCP client → MCP server: delegates browser task (evidence: `README.md`)
- MCP server → Browser bridge: starts and awaits runs (evidence: `mcp-server/src/index.ts`)
- Browser bridge → Agent loop: commands browser
- LM Studio user → LM Studio plugin: uses tools (evidence: `lmstudio-plugin/src/index.ts`)
- LM Studio plugin → URL research tools: calls research tools (evidence: `lmstudio-plugin/src/index.ts`)
- LM Studio plugin → Bridge client: delegates browser tasks (evidence: `lmstudio-plugin/src/index.ts`)
- Bridge client → Agent loop: sends browser commands
