How adiwanwade/webhawkai works
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