# gregpr07/browser-use architecture

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

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

## Overview

##### Main Components

a) Core Components:
- Agent System
- Browser Control Layer
- DOM Processing System
- Controller System
- Message Management System
- Telemetry System

b) External Integrations:
- LLM Services (OpenAI, Anthropic)
- Playwright Browser
- Custom Action Registry

**Top Layer: Client Applications/Examples**
**Middle Layer: Core Systems**
**Bottom Layer: External Services/Integrations**

##### Component Relationships

a) Agent Layer:
- Connections to:
- Message Manager (for LLM communication)
- Controller (for action execution)
- Browser (for web interactions)

b) Browser Layer:
- To DOM Processing
- Context Management
- Multi-tab support

c) Controller Layer:
- Registry connection
- Custom action registration flow
- To Browser and Agent

##### Specific Implementation Details

- Rectangles: Core components
- Hexagons: External services

##### Key Flows to Highlight

a) Main Execution Flow:
**Agent → Controller → Browser → DOM Processing → LLM → Agent**

b) Custom Action Flow:
**Controller Registry → Controller → Agent**

##### Important Architectural Patterns

- Async/await patterns
- Parallel agent support
- Browser context management

##### Specific Elements

**🔷 Core Component**
**🔶 External Service**
**⚡ Action Flow**
**💾 State Management**

##### Technical Details

Annotations for:
- Python 3.11+ requirement
- Playwright integration
- LangChain compatibility
- Custom action registration
- Telemetry options

##### Implementation Notes

- The modular nature of the system
- The ability to parallelize agents
- The flexibility in LLM selection
- The custom action registration system
- The browser context management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and Classes
    classDef agentLayer fill:#e1f5fe,stroke:#01579b
    classDef browserLayer fill:#e8f5e9,stroke:#1b5e20
    classDef domLayer fill:#fff3e0,stroke:#e65100
    classDef controllerLayer fill:#f3e5f5,stroke:#4a148c
    classDef external fill:#eceff1,stroke:#263238
    classDef process fill:#fff,stroke:#666
    classDef step fill:#f5f5f5,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1[Agent Layer]:::agentLayer
        L2[Browser Layer]:::browserLayer
        L3[DOM Layer]:::domLayer
        L4[Controller Layer]:::controllerLayer
        L5[External Services]:::external
        L6[Process Step]:::step
    end

    %% External Services
    LangChain[LangChain]:::external
    Playwright[Playwright]:::external
    CustomHooks[Custom Action Hooks]:::external

    %% Process Steps
    Step1["Step 1: Agent Initialization"]:::step
    Step2["Step 2: Browser Control"]:::step
    Step3["Step 3: DOM Processing"]:::step
    Step4["Step 4: Action Execution"]:::step
    Step5["Step 5: Result Generation"]:::step

    %% Agent Layer
    subgraph AgentLayer[Agent Layer]
        MessageManager[Message Manager]:::agentLayer
        PromptsSystem[Prompts System]:::agentLayer
        AgentService[Agent Service]:::agentLayer
    end

    %% Browser Layer
    subgraph BrowserLayer[Browser Layer]
        BrowserController[Browser Controller]:::browserLayer
        ContextManager[Context Manager]:::browserLayer
        PageController[Page Controller]:::browserLayer
    end

    %% DOM Layer
    subgraph DOMLayer[DOM Layer]
        DOMTreeBuilder[DOM Tree Builder]:::domLayer
        HistoryTreeProcessor[History Tree Processor]:::domLayer
        ElementExtractor[Element Extractor]:::domLayer
    end

    %% Controller Layer
    subgraph ControllerLayer[Controller Layer]
        Registry[Registry]:::controllerLayer
        ActionHandler[Action Handler]:::controllerLayer
        ServiceController[Service Controller]:::controllerLayer
    end

    %% Process Flow
    Step1 --> MessageManager
    Step1 --> PromptsSystem
    Step1 --> Registry

    MessageManager --> Step2
    Step2 --> BrowserController
    BrowserController --> ContextManager
    ContextManager --> PageController

    PageController --> Step3
    Step3 --> DOMTreeBuilder
    DOMTreeBuilder --> ElementExtractor
    ElementExtractor --> HistoryTreeProcessor

    HistoryTreeProcessor --> Step4
    Step4 --> ActionHandler
    ActionHandler --> ServiceController
    ServiceController --> Registry

    Registry --> Step5
    Step5 --> AgentService
    AgentService --> MessageManager

    %% External Connections
    LangChain --> PromptsSystem
    Playwright --> BrowserController
    CustomHooks --> Registry

    %% Click Events
    click MessageManager "https://github.com/gregpr07/browser-use/blob/main/browser_use/agent/message_manager/service.py"
    click PromptsSystem "https://github.com/gregpr07/browser-use/blob/main/browser_use/agent/prompts.py"
    click AgentService "https://github.com/gregpr07/browser-use/blob/main/browser_use/agent/service.py"
    click BrowserController "https://github.com/gregpr07/browser-use/blob/main/browser_use/browser/browser.py"
    click ContextManager "https://github.com/gregpr07/browser-use/blob/main/browser_use/browser/context.py"
    click PageController "https://github.com/gregpr07/browser-use/blob/main/browser_use/browser/views.py"
    click DOMTreeBuilder "https://github.com/gregpr07/browser-use/blob/main/browser_use/dom/buildDomTree.js"
    click HistoryTreeProcessor "https://github.com/gregpr07/browser-use/blob/main/browser_use/dom/history_tree_processor/service.py"
    click ElementExtractor "https://github.com/gregpr07/browser-use/blob/main/browser_use/dom/service.py"
    click Registry "https://github.com/gregpr07/browser-use/blob/main/browser_use/controller/registry/service.py"
    click ActionHandler "https://github.com/gregpr07/browser-use/blob/main/browser_use/controller/service.py"
    click ServiceController "https://github.com/gregpr07/browser-use/blob/main/browser_use/controller/views.py"
```
