# strongcomic/web-ui architecture

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

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

## Overview

##### Project Identification & Purpose
- This is a full-stack application with a focus on a WebUI built with Gradio. It extends the capabilities of the browser-use project by allowing users to interact with AI browser agents while integrating multiple LLMs (Google, OpenAI, Anthropic, etc.) and offering custom browser support and persistent sessions.
- The design involves both direct UI interaction (Gradio based frontend) and backend modules that coordinate browser operations, LLM calls, and custom agent behavior.

##### Analysis of File Structure
- At the top level, configuration files (Dockerfile, docker-compose.yml, .env.example) and scripts (entrypoint.sh, supervisord.conf) suggest that containerization and deployment are integral.
- The src/ directory is broken down into key submodules:
- agent: Contains logic for custom agent behavior (custom_agent.py, custom_message_manager.py, custom_prompts.py, custom_views.py). This module likely orchestrates AI interactions and task handling.
- browser: Contains custom browser modules (custom_browser.py, custom_context.py) that manage browser interactions and state.
- controller: Contains custom_controller.py, indicating higher-level coordination between various components.
- utils: Utility functions and configurations used across the system (agent state management, deep research routines, default settings, LLM integrations, etc.).
- The webui.py file is the entry point for launching the Gradio UI.
- Tests are provided to validate major components like browser usage, deep research logic, LLM API, and playwright integration.

##### Main Components
- WebUI Frontend:
- Represents the Gradio-based interface through which users interact. Also includes themes and configuration options.
- Agent & Controller Layer:
- Browser Module:
- Custom browser integration (custom_browser and custom_context) that allows persistent sessions, custom paths, and handles browser-specific interactions.
- Utility Services:
- Components from the utils folder as supporting services (for managing LLM integrations, deep research modules, configuration settings, etc.).
- External Services and APIs:
- Docker & Deployment: Represent Docker orchestration components and container management (Dockerfile, docker-compose) which encapsulate the entire system.
- Persistent State & Session Management:

##### Relationships and Interactions
- The WebUI sends user commands to the Controller.
- The Controller activates appropriate Agent modules which, in turn, coordinate with the Browser module and invoke Utility functions.
- The browser module interacts with external websites and possibly returns data to agents via the controller.
- Utility components (LLM integrations) send queries to external APIs and return responses that are then processed by the agents.

##### Architectural Patterns & Technologies
- The system embraces a layered architecture separating the UI, business logic (agents and controller), and browser interaction layers.
- The project leverages common design principles such as separation of concerns (by maintaining clearly distinct directories for agent, browser, controller, and utils).
- That the system is built upon:
- Python 3.11
- Gradio for the UI
- Docker for containerization
- Integration with multiple LLMs
- Playwright for browser automation (as indicated by tests and setup instructions)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Application Layers
    subgraph "Application Layers"
        A["WebUI (Gradio Frontend)"]:::frontend
        B["Controller Layer"]:::controller
        C["Agent Modules"]:::agent
        D["Browser Module (Persistent Sessions)"]:::browser
        E["Utility Services"]:::utility
        F["External LLM APIs"]:::external
    end

    A -->|"sendsCommands"| B
    B -->|"activates"| C
    C -->|"coordinatesWith"| D
    D -->|"returnsData"| C
    C -->|"usesUtilities"| E
    E -->|"queries"| F

    %% Infrastructure Layer with Docker & Deployment configuration
    subgraph "Infrastructure"
        G["Docker Container"]:::deployment
        subgraph "Deployment Config Files"
            H["Dockerfile"]:::config
            I["docker-compose.yml"]:::config
            J[".env.example"]:::config
            K["entrypoint.sh"]:::config
            L["supervisord.conf"]:::config
        end
    end

    H -->|"configures"| G
    I -->|"configures"| G
    J -->|"configures"| G
    K -->|"configures"| G
    L -->|"configures"| G

    G ---|"runs"| A
    G ---|"runs"| B
    G ---|"runs"| C
    G ---|"runs"| D
    G ---|"runs"| E

    %% Click Events mapping
    click A "https://github.com/strongcomic/web-ui/blob/main/webui.py"
    click B "https://github.com/strongcomic/web-ui/blob/main/src/controller/custom_controller.py"
    click C "https://github.com/strongcomic/web-ui/tree/main/src/agent/"
    click D "https://github.com/strongcomic/web-ui/tree/main/src/browser/"
    click E "https://github.com/strongcomic/web-ui/tree/main/src/utils/"
    click H "https://github.com/strongcomic/web-ui/tree/main/Dockerfile"
    click I "https://github.com/strongcomic/web-ui/blob/main/docker-compose.yml"
    click J "https://github.com/strongcomic/web-ui/blob/main/.env.example"
    click K "https://github.com/strongcomic/web-ui/blob/main/entrypoint.sh"
    click L "https://github.com/strongcomic/web-ui/blob/main/supervisord.conf"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef controller fill:#ffa07a,stroke:#333,stroke-width:2px;
    classDef agent fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef browser fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef utility fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef external fill:#ff6961,stroke:#333,stroke-width:2px;
    classDef deployment fill:#ffc0cb,stroke:#333,stroke-width:2px;
    classDef config fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
