# eonisailabs/browser-use architecture

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

- Interactive diagram: https://gitdiagram.com/eonisailabs/browser-use
- Repository: https://github.com/eonisailabs/browser-use

## Overview

##### Project type and purpose
- This is an open-source Python library (with CLI) that enables AI agents to control a web browser programmatically.
- Key features: agent orchestration, LLM integration, DOM extraction, controller/command execution, telemetry, filesystem interaction, multi-agent sync.

##### High-level component breakdown
A. Entry Points
– CLI (“browser-use”) and Python API (import browser_use.Agent)
– bin/setup.sh, bin/lint.sh, bin/test.sh (dev scripts)
B. Core Agent Layer
– Agent class (browser_use/agent/service.py)
– Message Manager (parses LLM responses into structured commands)
– Prompts & System Prompt templates (browser_use/agent/prompts.py, .md)
C. LLM Integration Layer
– Abstract base (browser_use/llm/base.py) and exceptions
– Provider adapters: OpenAI, Anthropic, Google, AWS (Bedrock & Anthropic), Azure, Groq, Ollama
– Serializer & parser per provider
D. Controller Layer
– Registry of commands/actions (browser_use/controller/registry)
– Services & Views to execute commands on the browser abstraction
– Tests for custom structured outputs
E. Browser Abstraction Layer
– Wrapper over Playwright (browser_use/browser/browser.py)
– Session, Profile, Context management
– Extensions, utilities, views for high-level browser actions
F. DOM Processing Layer
– Services to build and traverse DOM tree (buildDomTree.js, history tree, clickable element processor)
– Exposed views for agent to inspect page state
G. Filesystem, Sync, Telemetry, Tokens
– filesystem service to read/write files
– sync service for multi-agent event streaming & auth
– telemetry service to log events and metrics
– tokens service to count usage & cost
H. Configuration & Utilities
– browser_use/config.py, logging_config.py, utils.py
I. External Dependencies and Services
– Playwright (Chromium)
– LLM endpoints (OpenAI, Anthropic, etc.)
– Docker images (for cloud/CI use)

##### Interactions and data flow
1. User issues a task (via CLI or Python script) → Agent receives task + config
2. Agent sends a chat request to LLM adapter → receives text response
3. Message Manager parses response into structured commands (e.g., click, input, navigate)
4. Controller looks up command in registry → invokes Browser Service with parameters
5. Browser Service executes via Playwright → DOM Service extracts updated page state
6. Feedback loop: updated DOM fed back into prompts for next LLM request
7. Throughout:
- Telemetry logs each step,
- Tokens service accumulates cost,
- Filesystem service handles uploads/downloads or data persistence,
- Sync service propagates events if multiple agents are coordinating

##### Architectural patterns and principles
- Layered architecture (Entry → Agent → Domain Modules → Infra → External)
- Plugin/adapter pattern for LLM providers and controller commands
- Separation of concerns: parsing (message_manager), execution (controller), I/O (browser, filesystem), monitoring (telemetry)
- Registry pattern for discoverability of custom actions
- Test-driven design with extensive test suites for each module

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        CLI["CLI: browser-use"]:::entry
        API["Python API\n(browser_use/__init__.py)"]:::entry
        DevScripts["Dev Scripts\n(bin/*.sh)"]:::entry
    end

    CLI -->|issues task| AgentCore
    API -->|imports| AgentCore

    %% Core Agent Layer
    subgraph "Core Agent Layer"
        AgentCore["Agent Service\n(browser_use/agent/service.py)"]:::core
        MsgManager["Message Manager\n(service, utils, views)"]:::core
        Prompts["Prompts & Templates\n(prompts.py, .md)"]:::core
    end

    AgentCore -->|calls| MsgManager
    AgentCore -->|uses| Prompts

    %% LLM Integration Layer
    subgraph "LLM Integration Layer"
        BaseAdapter["Base Adapter\n(base.py, exceptions.py)"]:::llm
        ProviderAdapters["Provider Adapters\n(openai, anthropic, aws, azure, groq, ollama)"]:::llm
        SharedModels["Shared Models & Messages\n(messages.py, schema.py)"]:::llm
        LLMViews["LLM Views\n(views.py)"]:::llm
    end

    MsgManager -->|sends chat request| BaseAdapter
    BaseAdapter -->|routes to| ProviderAdapters
    SharedModels --> ProviderAdapters
    ProviderAdapters -->|calls| LLMAPI["LLM Provider APIs"]:::external
    LLMAPI -->|response| BaseAdapter
    BaseAdapter -->|returns| MsgManager

    %% Controller Layer
    subgraph "Controller Layer"
        Registry["Registry\n(service.py, views.py)"]:::core
        ControllerSvc["Controller Service & Views\n(service.py, views.py)"]:::core
    end

    MsgManager -->|parses commands| Registry
    Registry -->|look up| ControllerSvc
    ControllerSvc -->|executes| BrowserSvc

    %% Browser & DOM Layers
    subgraph "Browser Abstraction & DOM Processing"
        subgraph "Browser Abstraction"
            BrowserSvc["Browser Service\n(browser.py, session, context, profile)"]:::browser
            BrowserViews["Browser Views\n(views.py)"]:::browser
        end
        subgraph "DOM Processing"
            DOMSvc["DOM Service\n(service.js)"]:::browser
            BuildTree["Build DOM Tree\n(buildDomTree.js)"]:::browser
            ClickProcessor["Clickable Element Processor"]:::browser
            HistoryProc["History Tree Processor"]:::browser
            DOMViews["DOM Views\n(views.py)"]:::browser
        end
    end

    ControllerSvc -->|invoke| BrowserSvc
    BrowserSvc -->|executes on| Playwright["Playwright/Chromium"]:::external
    BrowserSvc -->|fetch state| DOMSvc
    DOMSvc -->|builds| BuildTree
    DOMSvc -->|processes| ClickProcessor
    DOMSvc -->|tracks| HistoryProc
    DOMSvc -->|provides| DOMViews
    DOMSvc -->|state feedback| MsgManager

    %% Infrastructure Layer
    subgraph "Infrastructure Services"
        FS["Filesystem\n(file_system.py)"]:::infra
        SyncSvc["Sync Service\n(service.py, auth.py)"]:::infra
        Telemetry["Telemetry\n(service.py, views.py)"]:::infra
        Tokens["Tokens\n(service.py, views.py)"]:::infra
    end

    AgentCore -->|logs| Telemetry
    AgentCore -->|counts| Tokens
    AgentCore -->|reads/writes| FS
    AgentCore -->|sync events| SyncSvc

    %% Click Events
    click CLI "https://github.com/eonisailabs/browser-use/blob/main/browser_use/cli.py"
    click API "https://github.com/eonisailabs/browser-use/blob/main/browser_use/__init__.py"
    click DevScripts "https://github.com/eonisailabs/browser-use/tree/main/bin/"
    click AgentCore "https://github.com/eonisailabs/browser-use/blob/main/browser_use/agent/service.py"
    click MsgManager "https://github.com/eonisailabs/browser-use/blob/main/browser_use/agent/message_manager/service.py"
    click Prompts "https://github.com/eonisailabs/browser-use/blob/main/browser_use/agent/prompts.py"
    click BaseAdapter "https://github.com/eonisailabs/browser-use/blob/main/browser_use/llm/base.py"
    click ProviderAdapters "https://github.com/eonisailabs/browser-use/blob/main/browser_use/llm/openai/chat.py"
    click Registry "https://github.com/eonisailabs/browser-use/blob/main/browser_use/controller/registry/service.py"
    click ControllerSvc "https://github.com/eonisailabs/browser-use/blob/main/browser_use/controller/service.py"
    click BrowserSvc "https://github.com/eonisailabs/browser-use/blob/main/browser_use/browser/browser.py"
    click DOMSvc "https://github.com/eonisailabs/browser-use/blob/main/browser_use/dom/service.py"
    click FS "https://github.com/eonisailabs/browser-use/blob/main/browser_use/filesystem/file_system.py"
    click SyncSvc "https://github.com/eonisailabs/browser-use/blob/main/browser_use/sync/service.py"
    click Telemetry "https://github.com/eonisailabs/browser-use/blob/main/browser_use/telemetry/service.py"
    click Tokens "https://github.com/eonisailabs/browser-use/blob/main/browser_use/tokens/service.py"

    %% Styles
    classDef entry fill:#a3d5d3,stroke:#333,stroke-width:1px
    classDef core fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef llm fill:#d9ead3,stroke:#333,stroke-width:1px
    classDef browser fill:#f9cb9c,stroke:#333,stroke-width:1px
    classDef infra fill:#d9d2e9,stroke:#333,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
