# adiwanwade/webhawkai architecture

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

- Interactive diagram: https://gitdiagram.com/adiwanwade/webhawkai
- Repository: https://github.com/adiwanwade/webhawkai

## Overview

##### Project Type and Purpose
- This is a full-stack Python application that orchestrates multiple “agent” modules (e.g., browser automation, deep-research) behind a central controller and exposes a Web UI to configure, launch, and monitor those agents. It uses external Large Language Model (LLM) APIs and a “MCP” service and runs everything in Docker/Supervisor for process management.

##### File-Structure Analysis
- Top-level artifacts:
- Dockerfile, docker-compose.yml, supervisord.conf – container and process orchestration
- webui.py – application entry point for the Web UI server
- requirements.txt – Python dependencies
- src/ directory organized by component:
- src/agent – various agent implementations (browser_use_agent, deep_research_agent)
- src/browser – abstraction over Playwright or other browser contexts
- src/controller – central controller that coordinates agents
- src/utils – cross-cutting services (config loader, llm_provider, mcp_client, general utils)
- src/webui – UI layer: components, manager, interface definitions
- tests/ for unit and integration tests (agents, controller, llm API, Playwright)

##### Key Insights from README (inferred)
- Core goal: provide an extensible framework where new agents plug into a controller and are exposed to users via a web interface
- Interactions with two main external services: LLM API provider and an MCP microservice
- Uses Docker and Supervisor to guarantee each component can be managed independently

a. Main Components
- Web UI Server (webui.py + src/webui)
- Controller Service (src/controller)
- Agent Modules (src/agent/browser_use, src/agent/deep_research)
- Browser Automation Layer (src/browser custom contexts)
- Utils Layer (LLM Provider, MCP Client, Config)
- External Services: LLM API, MCP microservice
b. Interactions
1. User → Web UI (HTTP/WebSocket)
2. Web UI → Controller (internal API calls)
3. Controller → Agents (in-process method invocations or inter-process via Supervisor)
4. Agents → Browser layer for automation tasks
5. Agents → Utils/LLM provider for LLM calls
6. Agents → MCP client for microservice communication
7. Results flow back up: Agents → Controller → Web UI → User
c. Architectural Patterns
- Layered architecture: UI layer → controller layer → agent layer → infrastructure (browser, LLM, MCP)
- Plugin pattern for agents—each new agent is a self-contained module under src/agent
- Process orchestration via Supervisor inside Docker containers for fault isolation
d. Technologies & Frameworks
- Python 3.x, Playwright (or custom browser wrapper)
- Flask/FastAPI (presumed) or similar for Web UI
- Docker + docker-compose + supervisord
- Testing with pytest

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Docker Container"
        subgraph "Supervisor Processes"
            UI["Web UI Server"]:::ui
            Controller["Controller Service"]:::backend
            subgraph "Agent Modules"
                BrowserUseAgent["BrowserUseAgent"]:::backend
                DeepResearchAgent["DeepResearchAgent"]:::backend
            end
        end
        subgraph "Utils Layer"
            Config["Config Loader"]:::infra
            LLMProvider["LLM Provider"]:::infra
            MCPClient["MCP Client"]:::infra
            Utils["General Utilities"]:::infra
        end
        subgraph "Browser Automation Layer"
            CustomBrowser["CustomBrowser"]:::infra
            CustomContext["CustomContext"]:::infra
        end
    end

    subgraph "Container & Process Orchestration"
        DockerfileNode["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
        SupervisorCfg["supervisord.conf"]:::infra
    end

    subgraph "External Services"
        LLMAPI["LLM API"]:::external
        MCPService["MCP Microservice"]:::external
    end

    %% User interactions
    User["User"]:::external
    User -->|"HTTP/WebSocket"| UI
    UI -->|"internal API"| Controller

    %% Controller to Agents
    Controller -->|"invoke"| BrowserUseAgent
    Controller -->|"invoke"| DeepResearchAgent

    %% Agents to infrastructure
    BrowserUseAgent -->|"Playwright RPC"| CustomBrowser
    BrowserUseAgent -->|"context"| CustomContext
    DeepResearchAgent -->|"Playwright RPC"| CustomBrowser
    DeepResearchAgent -->|"context"| CustomContext

    BrowserUseAgent -->|"LLM call"| LLMProvider
    DeepResearchAgent -->|"LLM call"| LLMProvider
    BrowserUseAgent -->|"MCP request"| MCPClient
    DeepResearchAgent -->|"MCP request"| MCPClient

    %% Utils to external
    LLMProvider -->|"API call"| LLMAPI
    MCPClient -->|"RPC"| MCPService

    %% Config distribution
    Config --> UI
    Config --> Controller
    Config --> BrowserUseAgent
    Config --> DeepResearchAgent
    Config --> CustomBrowser
    Config --> CustomContext
    Config --> LLMProvider
    Config --> MCPClient

    %% Results backflow
    BrowserUseAgent -->|"result"| Controller
    DeepResearchAgent -->|"result"| Controller
    Controller -->|"update"| UI
    UI -->|"response"| User

    %% Click Events
    click UI "https://github.com/adiwanwade/webhawkai/blob/main/webui.py"
    click Controller "https://github.com/adiwanwade/webhawkai/blob/main/src/controller/custom_controller.py"
    click BrowserUseAgent "https://github.com/adiwanwade/webhawkai/blob/main/src/agent/browser_use/browser_use_agent.py"
    click DeepResearchAgent "https://github.com/adiwanwade/webhawkai/blob/main/src/agent/deep_research/deep_research_agent.py"
    click CustomBrowser "https://github.com/adiwanwade/webhawkai/blob/main/src/browser/custom_browser.py"
    click CustomContext "https://github.com/adiwanwade/webhawkai/blob/main/src/browser/custom_context.py"
    click Config "https://github.com/adiwanwade/webhawkai/blob/main/src/utils/config.py"
    click LLMProvider "https://github.com/adiwanwade/webhawkai/blob/main/src/utils/llm_provider.py"
    click MCPClient "https://github.com/adiwanwade/webhawkai/blob/main/src/utils/mcp_client.py"
    click Utils "https://github.com/adiwanwade/webhawkai/blob/main/src/utils/utils.py"
    click DockerfileNode "https://github.com/adiwanwade/webhawkai/tree/main/Dockerfile"
    click Compose "https://github.com/adiwanwade/webhawkai/blob/main/docker-compose.yml"
    click SupervisorCfg "https://github.com/adiwanwade/webhawkai/blob/main/supervisord.conf"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef backend fill:#ccffcc,stroke:#33cc33,color:#000;
    classDef infra fill:#e6e6e6,stroke:#999,color:#000;
    classDef external fill:#ffebcc,stroke:#ff9900,color:#000;
```
