# timecyber/deepmanus architecture

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

- Interactive diagram: https://gitdiagram.com/timecyber/deepmanus
- Repository: https://github.com/timecyber/deepmanus

## Overview

##### Main Components
- Core Engine/Workflow:
- Entry points: main.py and server.py (API server using FastAPI)
- Workflow management from src/workflow.py and the orchestration mechanics in src/service/workflow_service.py
- Multi-Agent System:
- Agents: code under src/agents/agents.py along with role-specific prompts in src/prompts (each markdown file for Supervisor, Researcher, Coder, etc.)
- Coordination mechanism: the hierarchical layering (Coordinator, Planner, Supervisor) as described in README and reflected in the agent modules.
- LLM Integration:
- Several LLM integration components under src/llms for reasoning (litellm_v2.py, litellm_config.py) and the general llm.py
- Configurable through configuration files in src/config and the conf.yaml example.
- Web and API Layer:
- API endpoints are implemented in src/api/app.py with streaming capabilities.
- The project includes Docker and Docker Compose configurations for running both backend and a separate web UI (frontend) provided in the documentation.
- Auxiliary Components:
- Crawler: Modules in src/crawler for web scraping, handling article extraction, and interacting with external web services via browser automations (Playwright).
- Tools: Utility modules in src/tools for bash tools, file management, and search functions.
- Graph: Visualization or task workflow graph construction in src/graph.
- Config and environment management in src/config, complemented by .env and conf.yaml for flexible configuration.
- Testing and quality assurance scripts in tests/ and integration set up via Makefile and pre-commit.

##### Relationships and Interactions
- The API server (backend) acts as an entry point for external requests. It will forward tasks to the multi-agent system that uses the hierarchical agent roles.
- The Coordinator (entry agent) receives a task request and delegates specific portions to specialized agents (e.g., Planner, Supervisor, Researcher, Coder).
- Each agent interacts with the LLM layer to generate responses or execute actions.
- The crawler and browser components employ Playwright (via src/playwright_manager.py and browser_use) to retrieve external data.
- The configuration modules (under src/config) provide standardized parameters and environment setups for agents and LLM integrations.
- Tools and utilities enrich functionality, while testing and pre-commit hooks ensure code quality.

##### Architectural Patterns and Design Principles
- Modular design: The project is organized into clear modules (agents, api, config, crawler, tools, utils), reflecting a separation of concerns.
- Multi-agent orchestration: Hierarchical multi-agent system where responsibilities are divided among specialized agents.
- Extensibility: Role-based prompt templates allow addition or customization of agent behavior without changing core logic.
- Integration-oriented design: Built-in support for multiple LLM providers (via litellm), external tools, and browser automation.
- Configuration flexibility: Use of environment variables and layered configuration (conf.yaml vs. .env), making the system adaptable to different deployment scenarios.

##### Relevant Technologies, Frameworks, and Libraries
- Python 3.12+ for the core implementation.
- FastAPI (in src/api/app.py) for the REST API server.
- Playwright integration (see src/playwright_manager.py and browser_use folder) for browser automation.
- Docker and docker-compose for containerized deployment.
- uv package manager for dependency management.
- Pre-commit hooks for linting and formatting, ensuring code quality.

##### Elements
- Clear labels for each primary component: API Server, Workflow Manager, Multi-Agent System (with individual agent roles like Coordinator, Planner, Supervisor, Researcher, Coder, Browser, Reporter), LLM Integration, Configuration Manager, Crawler/Browser Modules, and Auxiliary Tools.
- User/API requests flowing into the API server, then to the Coordinator.
- Task delegation from the Coordinator to other agents.
- Data coming from external sources (via crawler/browser) feeding into agents for processing.
- Final responses being routed back to the API server for client delivery.
- Core application logic (e.g., multi-agent orchestration modules)
- External interfaces (API endpoints, browser automation components)
- Configuration and utility layers.
- Important integration points such as database connections (if any), LLM service configurations, and Docker components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level User and API Server
    User(["User/API Client"]):::user
    APIServer(["API Server (FastAPI)"]):::api

    User -->|"requests"| APIServer

    %% Workflow Engine Subgraph
    subgraph "Workflow Engine"
        EntryMain(["main.py"]):::workflow
        EntryServer(["server.py"]):::workflow
        WorkflowProc(["Workflow Management\\n(src/workflow.py)"]):::workflow
        WorkflowService(["Workflow Service\\n(src/service/workflow_service.py)"]):::workflow
        EntryMain --> EntryServer
        EntryServer --> WorkflowProc
        WorkflowProc --> WorkflowService
    end

    %% API Server integration with Workflow Engine and Multi-Agent System
    APIServer -->|"triggers"| WorkflowProc

    %% Multi-Agent System Subgraph
    subgraph "Multi-Agent System"
        AgentLogic(["Agent Logic\\n(src/agents/agents.py)"]):::agent
        Coordinator(["Coordinator Agent"]):::agent
        Planner(["Planner Agent"]):::agent
        Supervisor(["Supervisor Agent"]):::agent
        Researcher(["Researcher Agent"]):::agent
        Coder(["Coder Agent"]):::agent
        Browser(["Browser Agent"]):::agent
        Reporter(["Reporter Agent"]):::agent

        AgentLogic --> Coordinator
        AgentLogic --> Planner
        AgentLogic --> Supervisor
        AgentLogic --> Researcher
        AgentLogic --> Coder
        AgentLogic --> Browser
        AgentLogic --> Reporter
    end

    %% API Server routes request to Multi-Agent System
    APIServer -->|"routes request"| Coordinator

    %% Task delegation within Multi-Agent System
    Coordinator -->|"delegates"| Planner
    Coordinator -->|"delegates"| Supervisor
    Coordinator -->|"delegates"| Researcher
    Coordinator -->|"delegates"| Coder
    Coordinator -->|"delegates"| Browser
    Coordinator -->|"delegates"| Reporter

    %% LLM Integration Subgraph
    subgraph "LLM Integration"
        LLMCore(["LLM Core\\n(src/llms/llm.py)"]):::llm
        LiteLLM(["LiteLLM V2\\n(src/llms/litellm_v2.py)"]):::llm
        LiteConfig(["LiteLLM Config\\n(src/llms/litellm_config.py)"]):::llm
    end

    %% Agents interacting with LLM Integration
    Coordinator -->|"consults"| LLMCore
    Planner -->|"consults"| LLMCore
    Supervisor -->|"consults"| LLMCore
    Researcher -->|"consults"| LLMCore
    Coder -->|"consults"| LLMCore
    Browser -->|"consults"| LLMCore
    Reporter -->|"consults"| LLMCore

    %% Crawler & Browser Automation Subgraph
    subgraph "Crawler & Browser Automation"
        Crawler(["Crawler Module\\n(src/crawler/)"]):::crawlbrowser
        Playwright(["Playwright Manager\\n(src/playwright_manager.py)"]):::crawlbrowser
        BrowserAuto(["Browser Automation\\n(browser_use/)"]):::crawlbrowser
    end

    %% Integration of external data
    Crawler -->|"feeds"| Researcher
    Playwright -->|"supports"| Browser
    BrowserAuto -->|"supports"| Browser

    %% Auxiliary Tools Subgraph
    subgraph "Auxiliary Tools"
        Tools(["Utility Tools\\n(src/tools/)"]):::tools
        Graph(["Graph Construction\\n(src/graph/)"]):::tools
        Config(["Configuration Manager\\n(src/config/)"]):::tools
    end

    %% Configuration supports multiple components
    Config -->|"configures"| APIServer
    Config -->|"configures"| WorkflowProc
    Config -->|"configures"| Coordinator
    Config -->|"configures"| LLMCore

    %% Docker & Deployment and Testing & CI
    Docker(["Docker & Deployment"]):::docker
    Testing(["Testing & CI\\n(tests/, Makefile, pre-commit)"]):::testing

    %% Integration of Deployment and Testing with API and Workflow
    Docker -->|"deploys"| APIServer
    Testing -->|"validates"| WorkflowProc
    Testing -->|"validates"| AgentLogic

    %% Click Events for Workflow Engine Entry Points
    click EntryMain "https://github.com/timecyber/deepmanus/blob/main/main.py"
    click EntryServer "https://github.com/timecyber/deepmanus/blob/main/server.py"
    click WorkflowProc "https://github.com/timecyber/deepmanus/blob/main/src/workflow.py"
    click WorkflowService "https://github.com/timecyber/deepmanus/blob/main/src/service/workflow_service.py"

    %% Click Event for API Server
    click APIServer "https://github.com/timecyber/deepmanus/blob/main/src/api/app.py"

    %% Click Event for Multi-Agent System
    click AgentLogic "https://github.com/timecyber/deepmanus/blob/main/src/agents/agents.py"
    click Coordinator "https://github.com/timecyber/deepmanus/blob/main/src/prompts/coordinator.md"
    click Planner "https://github.com/timecyber/deepmanus/blob/main/src/prompts/planner.md"
    click Supervisor "https://github.com/timecyber/deepmanus/blob/main/src/prompts/supervisor.md"
    click Researcher "https://github.com/timecyber/deepmanus/blob/main/src/prompts/researcher.md"
    click Coder "https://github.com/timecyber/deepmanus/blob/main/src/prompts/coder.md"
    click Browser "https://github.com/timecyber/deepmanus/blob/main/src/prompts/browser.md"
    click Reporter "https://github.com/timecyber/deepmanus/blob/main/src/prompts/reporter.md"

    %% Click Events for LLM Integration
    click LLMCore "https://github.com/timecyber/deepmanus/blob/main/src/llms/llm.py"
    click LiteLLM "https://github.com/timecyber/deepmanus/blob/main/src/llms/litellm_v2.py"
    click LiteConfig "https://github.com/timecyber/deepmanus/blob/main/src/llms/litellm_config.py"

    %% Click Events for Crawler & Browser Automation
    click Crawler "https://github.com/timecyber/deepmanus/tree/main/src/crawler/"
    click Playwright "https://github.com/timecyber/deepmanus/blob/main/src/playwright_manager.py"
    click BrowserAuto "https://github.com/timecyber/deepmanus/tree/main/browser_use/"

    %% Click Events for Auxiliary Tools
    click Tools "https://github.com/timecyber/deepmanus/tree/main/src/tools/"
    click Graph "https://github.com/timecyber/deepmanus/tree/main/src/graph/"
    click Config "https://github.com/timecyber/deepmanus/tree/main/src/config/"

    %% Click Event for Testing & CI
    click Testing "https://github.com/timecyber/deepmanus/tree/main/tests/"

    %% Styles
    classDef user fill:#FFE4B5,stroke:#D2691E,stroke-width:2px;
    classDef api fill:#ADD8E6,stroke:#000080,stroke-width:2px;
    classDef workflow fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef agent fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef llm fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef crawlbrowser fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef tools fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
    classDef docker fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef testing fill:#FDEBD0,stroke:#CA6F1E,stroke-width:2px;
```
