# browser-use/web-ui architecture

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

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

## Overview

##### Main Components

a) Frontend Layer:
- Gradio Web Interface (webui.py)
- Theme System (with multiple theme options)
- Dark/Light Mode Support

b) Core Components:
- Agent System (src/agent/)
- Browser Integration (src/browser/)
- Controller Layer (src/controller/)
- Utilities (src/utils/)

c) External Integrations:
- LLM Services (Gemini, OpenAI, Azure OpenAI, Anthropic, DeepSeek, Ollama)
- Browser Instances (Chrome/Custom Browser)
- Playwright Integration

**[User Interface Layer]**

**[Core Processing Layer]**

**[External Services Layer]**

##### Component Relationships

a) User Interface → Controller:
- How webui.py interfaces with custom_controller.py

b) Controller → Agent:
- How custom_controller.py manages custom_agent.py
- Message flow through custom_message_manager.py

c) Agent → Browser:
- Connection between custom_agent.py and custom_browser.py
- Context management via custom_context.py

d) External Services Integration:
- LLM API connections
- Browser instance management
- Playwright automation flow

##### Implementation Details

**[webui.py] → [custom_controller.py] → [custom_agent.py]**
- ↓
- [custom_browser.py]
- ↓
- [External Browser Instance]

##### Additional Elements

- Environment configuration flow (.env)
- Test coverage relationship (tests/ directory)
- Asset management (assets/ directory)

##### The central role of the agent system

Keep the abstraction level high enough to show the overall architecture while including sufficient detail to understand the interaction between components. Focus on showing how the system enables AI agents to interact with web browsers through the Gradio-based UI.

Remember to include version compatibility notes (Python 3.11+) and environment setup requirements as supplementary information.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph UI
        GradioUI["Gradio Web UI"]:::frontend
        VNCViewer["VNC Viewer"]:::frontend
    end

    subgraph Core
        Controller["Controller Layer"]:::core
        AgentSystem["Agent System"]:::core
        BrowserManager["Browser Manager"]:::core
    end

    subgraph External
        LLMServices["LLM Services"]:::external
        subgraph LLMProviders["LLM Providers"]
            OpenAI["OpenAI"]:::llm
            Gemini["Gemini"]:::llm
            Azure["Azure OpenAI"]:::llm
            Anthropic["Anthropic"]:::llm
            DeepSeek["DeepSeek"]:::llm
            Ollama["Ollama"]:::llm
        end
    end

    subgraph Browser
        BrowserInstance["Chrome/Browser Instance"]:::browser
        CustomBrowser["Custom Browser"]:::browser
    end

    subgraph Config
        EnvConfig["Environment Config"]:::config
        DockerConfig["Docker Config"]:::config
        ThemeSystem["Theme System"]:::config
    end

    subgraph Utils
        StateManagement["Agent State Management"]:::util
        MessageManagement["Message Management"]:::util
    end

    %% Relationships
    GradioUI <--> Controller
    Controller --> AgentSystem
    AgentSystem --> BrowserManager
    BrowserManager --> BrowserInstance
    BrowserManager <-.-> CustomBrowser
    BrowserInstance --> LLMServices
    BrowserInstance --> VNCViewer

    %% Configuration Dependencies
    EnvConfig -.-> Controller
    DockerConfig -.-> BrowserManager
    ThemeSystem -.-> GradioUI
    StateManagement -.-> AgentSystem
    MessageManagement -.-> AgentSystem

    %% Click Events
    click GradioUI "https://github.com/browser-use/web-ui/blob/main/webui.py"
    click AgentSystem "https://github.com/browser-use/web-ui/tree/main/src/agent/"
    click Controller "https://github.com/browser-use/web-ui/tree/main/src/controller/"
    click BrowserManager "https://github.com/browser-use/web-ui/tree/main/src/browser/"
    click CustomBrowser "https://github.com/browser-use/web-ui/blob/main/src/browser/custom_browser.py"
    click StateManagement "https://github.com/browser-use/web-ui/blob/main/src/utils/agent_state.py"
    click MessageManagement "https://github.com/browser-use/web-ui/blob/main/src/agent/custom_massage_manager.py"
    click EnvConfig "https://github.com/browser-use/web-ui/blob/main/.env.example"
    click DockerConfig "https://github.com/browser-use/web-ui/blob/main/docker-compose.yml"

    %% Styling
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef external fill:#f1c40f,stroke:#f39c12,color:black
    classDef browser fill:#e67e22,stroke:#d35400,color:white
    classDef config fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef util fill:#9b59b6,stroke:#8e44ad,color:white
    classDef llm fill:#f1c40f,stroke:#f39c12,color:black

    %% Legend
    subgraph Legend
        Frontend["Frontend Component"]:::frontend
        CoreComp["Core Component"]:::core
        ExternalComp["External Service"]:::external
        BrowserComp["Browser Component"]:::browser
        ConfigComp["Configuration"]:::config
        UtilComp["Utility"]:::util
    end
```
