# browser-use/browser-use-webui architecture

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

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

## Overview

##### Main Components
- WebUI Frontend: Represented by the entry point in webui.py and built on top of Gradio. This is where users interact with the system.
- Backend Modules:
- Agent Module (src/agent): Contains business logic like custom_agent.py, message management, prompts, and system prompts. These modules encapsulate the AI decision-making and LLM integration logic.
- Browser Module (src/browser): Handles browser automation and context management (e.g., custom_browser.py and custom_context.py) using Playwright (as hinted in installation instructions).
- Controller Module (src/controller): Orchestrates or manages interactions between the agents and browsers. This can be seen in custom_controller.py.
- Utils Module (src/utils): Provides utility functions such as agent state management, deep research logic, and LLM API utilities.
- Testing & Configuration:
- Tests directory: Contains tests validating different components (browser usage, deep research, LLM APIs, Playwright).
- Configuration Files: Files like Dockerfile, docker-compose.yml, .env.example, and supervisord.conf indicate containerization and environment management.

##### External & Supporting Elements
- LLM Integrations: The README highlights support for multiple LLMs (Google, OpenAI, Azure, Anthropic, DeepSeek, Ollama, etc.). Indicate these as external services that the Agent component communicates with.
- Browser/Playwright: Since the system relies on Playwright for browser control (for automated interaction and even VNC-based viewing), include this integration process.
- Persistent Browser Sessions: Highlight the persistent session feature that allows keeping the browser open between AI tasks (configured using environment variables).

##### Relationships & Interactions
- Data Flow:
- User requests (HTTP calls) go to the WebUI layer.
- The WebUI makes internal calls to the Controller, which in turn calls relevant Agent and Browser modules.
- The Agent communicates with external LLM services (API calls for text generation/processing) and uses utility functions for state management.
- The Browser module drives the actual web-browser automation (via Playwright), possibly sending interaction results back to the WebUI.
- Integration of Docker: The whole application is containerized – highlight how Docker abstracts the environment and deployment concerns.

##### Architectural Patterns and Design Principles
- Modularity: The code is organized into clear components (agent, browser, controller, utils) which promotes separation of concerns.
- Extensibility: With integrated support for multiple LLM providers and custom browser paths, the architecture is designed for extensibility.
- Containerization: Docker and Docker Compose are employed to encapsulate both development and deployment configurations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level User
    U["User"]:::external

    %% User Interaction Layer
    subgraph "User Interaction Layer"
        UI["Gradio Web UI"]:::webui
    end

    %% Backend Modules
    subgraph "Backend Modules"
        CTRL["Controller Module"]:::backend
        AGENT["Agent Module"]:::backend
        BROWSER["Browser Module"]:::backend
        UTILS["Utils Module"]:::backend
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM Integrations"]:::external
        PLAY["Playwright & Browser Control"]:::external
    end

    %% Infrastructure & Testing
    subgraph "Deployment & Support"
        INFRA["Containerization & Configuration"]:::infra
        TEST["Testing & Validation"]:::infra
    end

    %% Connections - User and UI
    U -->|"HTTPRequest"| UI

    %% UI to Controller
    UI -->|"APIcall"| CTRL

    %% Controller to Modules
    CTRL -->|"Dispatches"| AGENT
    CTRL -->|"Sends commands"| BROWSER

    %% Agent relations
    AGENT -->|"LLM API call"| LLM
    AGENT -->|"Utilizes"| UTILS

    %% Browser relations
    BROWSER -->|"Automates via PersistentSession"| PLAY

    %% Deployment & Support integration
    INFRA ---|"Environments"| UI
    INFRA ---|"Environments"| CTRL
    INFRA ---|"Environments"| AGENT
    INFRA ---|"Environments"| BROWSER
    INFRA ---|"Environments"| UTILS
    INFRA ---|"Environments"| TEST

    %% Testing validations
    TEST ---|"Validates"| CTRL
    TEST ---|"Validates"| AGENT
    TEST ---|"Validates"| BROWSER
    TEST ---|"Validates"| UTILS

    %% Click Events
    click UI "https://github.com/browser-use/browser-use-webui/blob/main/webui.py"
    click AGENT "https://github.com/browser-use/browser-use-webui/tree/main/src/agent"
    click BROWSER "https://github.com/browser-use/browser-use-webui/tree/main/src/browser"
    click CTRL "https://github.com/browser-use/browser-use-webui/blob/main/src/controller/custom_controller.py"
    click UTILS "https://github.com/browser-use/browser-use-webui/tree/main/src/utils"
    click TEST "https://github.com/browser-use/browser-use-webui/tree/main/tests"
    click INFRA "https://github.com/browser-use/browser-use-webui/tree/main/Dockerfile"

    %% Styles
    classDef webui fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef backend fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef external fill:#ffffcc,stroke:#999900,stroke-width:2px,stroke-dasharray: 5 5;
    classDef infra fill:#cce5ff,stroke:#004085,stroke-width:2px;
```
