# parsaghaffari/browserbee architecture

> Architecture diagram of the GitHub repository parsaghaffari/browserbee, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parsaghaffari/browserbee
- Repository: https://github.com/parsaghaffari/browserbee

## Overview

##### Project type and purpose
- BrowserBee is an open-source Chrome extension that embeds a lightweight AI agent in the browser.
- Its purpose is to let end users control the browser via natural-language instructions, using an LLM (Anthropic, OpenAI, Gemini, Ollama) for planning and Playwright (via playwright-crx) under the hood for browser automation.

##### File structure
- Top-level:
- public/ – static assets & extension entry pages (manifest.json, options.html, sidepanel.html)
- src/ – all extension source code, organized by feature/context
- docs/ – Docusaurus-based documentation site
- .github/, README.md, ROADMAP.md, etc. – project governance and CI
- Under src/:
- src/background/ – background script (Chrome extension background context)
- src/agent/ – the core AI agent modules (ExecutionEngine, MemoryManager, PromptManager, ToolManager, etc.)
- src/models/providers/ – adapters to various LLM APIs
- src/sidepanel/ + src/options/ – React-based UI for the side panel and options page
- src/tracking/ – local memory & token tracking (defaultMemories.json, memoryService.ts, tokenTrackingService.ts)
- src/types/ – TypeScript declarations (including Playwright CRX types)

##### README for additional insights
- Confirms:
- Entirely in-browser except outbound LLM API calls
- Uses Playwright-CRX for browser automation
- Tracks token usage and price
- Stores “memories” in local storage/IndexedDB for future reuse
- Requests user approval for sensitive actions

##### Main components
a. User Interface Context (Chrome Extension UI)
- Side Panel (React components under src/sidepanel)
- Options Page (src/options)
- Communication hook: useChromeMessaging (chrome.runtime.sendMessage / onMessage)
b. Background Context (src/background)
- messageHandler & agentController
- streamingManager (for LLM response streaming)
- configManager (loads/saves user API keys)
- tabManager (keeps track of open tabs & reattachment logic)
c. Agent Core (src/agent)
- ExecutionEngine (dispatches prompts → LLM → tool calls)
- PromptManager (formats instructions + memory)
- MemoryManager (save, lookup, delete memories via memoryService)
- TokenManager (tracks tokens via tokenTrackingService)
- ToolManager (orchestrates calls to browser_navigate, browser_click, etc.)
- ErrorHandler / approvalManager
d. Tool Layer
- Playwright-CRX adapter (in browser) for CDP commands
- Tool modules: navigationTools, interactionTools, mouseTools, keyboardTools, observationTools, tabTools, memoryTools
e. Model Providers (src/models/providers)
- openai.ts, anthropic.ts, gemini.ts, ollama.ts + factory.ts
- External HTTP APIs or local RPC (for Ollama)
f. Storage & Tracking (src/tracking)
- defaultMemories.json, memoryService.ts (IndexedDB or localStorage)
- tokenTrackingService (metrics & cost computation)

##### Relationships and data flows
- User types instruction → SidePanel UI
- UI sends a message to Background → messageHandler routes to agentController
- Controller invokes ExecutionEngine
- ExecutionEngine:
1. PromptManager builds a prompt (including lookupMemories)
2. Sends to ModelProvider → receives response stream → streamingManager emits tokens back to UI
3. Parses LLM response into tool calls → ToolManager invokes Playwright-CRX methods via CDP
4. Observes results via observation tools → loops or finalizes
5. MemoryManager may save a new memory after “reflect and learn”
6. TokenManager logs usage
- ConfigManager provides API keys/config to ModelProviders
- TabManager and PageContextManager handle which tab the agent is attached to

##### Architectural patterns and principles
- Extension multi-context pattern (UI <→> background scripts)
- Modular “agent core” separated from UI, tools, and model adapters
- Factory pattern for LLM provider selection
- Observer pattern for streaming token events
- Command pattern for each browser tool call

##### Detail
- Major modules in src/agent, src/background, src/models/providers, src/sidepanel
- Flows: User → UI → Background → LLM → Tools → Browser → UI
- Don’t omit the memory lookup/save cycle nor token tracking

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Extension UI"
    SP["Side Panel UI"]:::ui
    SPC["Side Panel Components"]:::ui
    UHOOK["useChromeMessaging Hook"]:::ui
    OPTS["Options Page UI (Options.tsx)"]:::ui
    OPIDX["Options Entry (index.tsx)"]:::ui
  end

  subgraph "Background & Agent Core"
    BG["Background Entry Point"]:::core
    MH["Message Handler"]:::core
    AC["Agent Controller"]:::core
    SM["Streaming Manager"]:::core
    CM["Config Manager"]:::core
    TMgr["Tab Manager"]:::core
    RC["Reflection Controller"]:::core
    EE["ExecutionEngine"]:::core
    PM["PromptManager"]:::core
    MemM["MemoryManager"]:::core
    TokM["TokenManager"]:::core
    ToolM["ToolManager"]:::core
    EU["ErrorHandler & ApprovalManager"]:::core
    PCM["PageContextManager"]:::core
  end

  subgraph "Tool Layer / Browser Automation"
    PLCRX["Playwright-CRX Adapter"]:::tool
    NavT["navigationTools"]:::tool
    IntT["interactionTools"]:::tool
    MouseT["mouseTools"]:::tool
    KeyT["keyboardTools"]:::tool
    ObsT["observationTools"]:::tool
    TabT["tabTools"]:::tool
    MemT["memoryTools"]:::tool
    TCtxT["tabContextTools"]:::tool
  end

  subgraph "Model Providers"
    FCT["Factory"]:::external
    OpenAI["OpenAI"]:::external
    Anthr["Anthropic"]:::external
    Gem["Gemini"]:::external
    Oll["Ollama"]:::external
  end

  subgraph "Storage & Tracking"
    DM["defaultMemories.json"]:::storage
    MS["Memory Service"]:::storage
    TTS["Token Tracking Service"]:::storage
    SS["Screenshot Manager"]:::storage
  end

  subgraph "External LLM APIs"
    Cloud["LLM Providers Cloud"]:::external
  end

  SP -->|sends instruction via| UHOOK
  OPTS -->|sends config via| UHOOK
  OPIDX -->|sends config via| UHOOK
  UHOOK -->|chrome.runtime.sendMessage| MH
  MH --> AC
  AC --> EE
  EE --> PM
  PM --> MemM
  MemM --> MS
  EE --> FCT
  FCT --> OpenAI
  FCT --> Anthr
  FCT --> Gem
  FCT --> Oll
  OpenAI -->|HTTP API| Cloud
  Anthr -->|HTTP API| Cloud
  Gem -->|HTTP API| Cloud
  Oll -->|RPC/HTTP| Cloud
  Cloud --> SM
  SM -->|stream tokens| SP
  EE --> ToolM
  ToolM --> PLCRX
  PLCRX --> NavT
  PLCRX --> IntT
  PLCRX --> MouseT
  PLCRX --> KeyT
  PLCRX --> ObsT
  PLCRX --> TabT
  PLCRX --> MemT
  PLCRX --> TCtxT
  EE --> TokM
  TokM --> TTS
  EE --> MemM
  EE --> EU
  AC --> TMgr
  TMgr --> PCM
  CM --> FCT
  DM --> MemM
  SS -.-> TTS

  click SP "https://github.com/parsaghaffari/browserbee/blob/main/src/sidepanel/SidePanel.tsx"
  click SPC "https://github.com/parsaghaffari/browserbee/tree/main/src/sidepanel/components/"
  click UHOOK "https://github.com/parsaghaffari/browserbee/blob/main/src/sidepanel/hooks/useChromeMessaging.ts"
  click OPTS "https://github.com/parsaghaffari/browserbee/blob/main/src/options/Options.tsx"
  click OPIDX "https://github.com/parsaghaffari/browserbee/blob/main/src/options/index.tsx"
  click BG "https://github.com/parsaghaffari/browserbee/blob/main/src/background/index.ts"
  click MH "https://github.com/parsaghaffari/browserbee/blob/main/src/background/messageHandler.ts"
  click AC "https://github.com/parsaghaffari/browserbee/blob/main/src/background/agentController.ts"
  click SM "https://github.com/parsaghaffari/browserbee/blob/main/src/background/streamingManager.ts"
  click CM "https://github.com/parsaghaffari/browserbee/blob/main/src/background/configManager.ts"
  click TMgr "https://github.com/parsaghaffari/browserbee/blob/main/src/background/tabManager.ts"
  click RC "https://github.com/parsaghaffari/browserbee/blob/main/src/background/reflectionController.ts"
  click EE "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/ExecutionEngine.ts"
  click PM "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/PromptManager.ts"
  click MemM "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/MemoryManager.ts"
  click TokM "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/TokenManager.ts"
  click ToolM "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/ToolManager.ts"
  click EU "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/ErrorHandler.ts"
  click EU "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/approvalManager.ts"
  click PCM "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/PageContextManager.ts"
  click NavT "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/tools/navigationTools.ts"
  click IntT "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/tools/interactionTools.ts"
  click MouseT "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/tools/mouseTools.ts"
  click KeyT "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/tools/keyboardTools.ts"
  click ObsT "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/tools/observationTools.ts"
  click TabT "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/tools/tabTools.ts"
  click MemT "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/tools/memoryTools.ts"
  click TCtxT "https://github.com/parsaghaffari/browserbee/blob/main/src/agent/tools/tabContextTools.ts"
  click FCT "https://github.com/parsaghaffari/browserbee/blob/main/src/models/providers/factory.ts"
  click OpenAI "https://github.com/parsaghaffari/browserbee/blob/main/src/models/providers/openai.ts"
  click Anthr "https://github.com/parsaghaffari/browserbee/blob/main/src/models/providers/anthropic.ts"
  click Gem "https://github.com/parsaghaffari/browserbee/blob/main/src/models/providers/gemini.ts"
  click Oll "https://github.com/parsaghaffari/browserbee/blob/main/src/models/providers/ollama.ts"
  click DM "https://github.com/parsaghaffari/browserbee/blob/main/src/tracking/defaultMemories.json"
  click MS "https://github.com/parsaghaffari/browserbee/blob/main/src/tracking/memoryService.ts"
  click TTS "https://github.com/parsaghaffari/browserbee/blob/main/src/tracking/tokenTrackingService.ts"
  click SS "https://github.com/parsaghaffari/browserbee/blob/main/src/tracking/screenshotManager.ts"

  classDef ui fill:#cce5ff,stroke:#004085,color:#004085
  classDef core fill:#d4edda,stroke:#155724,color:#155724
  classDef tool fill:#fff3cd,stroke:#856404,color:#856404
  classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
  classDef storage fill:#f8f9fa,stroke:#adb5bd,color:#6c757d
```
