# hkuds/auto-deep-research architecture

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

- Interactive diagram: https://gitdiagram.com/hkuds/auto-deep-research
- Repository: https://github.com/hkuds/auto-deep-research

## Overview

##### Main components
- Agents Module: Under autoagent/agents, you have several specialized agents (e.g., filesurfer_agent, programming_agent, system_triage_agent, and websurfer_agent). These agents are responsible for different system tasks.
- Environment Module: The autoagent/environment directory includes multiple submodules (browser environment, Docker environment, cookie management, TCP server, markdown browser, etc.) that set up the runtime context and manage external interactions.
- Flow Module: The autoagent/flow package handles routing and orchestration (broker, core, dynamic routing of tasks) which likely manages the control flow between agents.
- Tools Module: autoagent/tools provides peripheral utilities (dummy_tool, file_surfer_tool, terminal_tools, etc.) that the agents or pipelines can use.
- REPL and CLI: The autoagent/cli.py and autoagent/repl directory provide interfaces for user interaction (i.e., command-line commands, interactive sessions).
- Server and TCP Components: Files like autoagent/server.py and autoagent/tcp_server.py indicate that a server-based or networked interaction component exists.
- Workflows: The autoagent/workflows package may be used to encapsulate higher-level processes combining agents, tools, and environment setups for specific tasks.
- Configuration/Infrastructure: Files like .env.template, setup.cfg, pyproject.toml, and MANIFEST.in show that configuration management and packaging elements are also key parts of the design.

##### Out relationships and interactions
- The Flow layer then delegates tasks to one or more Agents – each agent (e.g., programming or file-surfing agent) having specialized responsibilities.
- Each Agent may interact with the Memory module to fetch or save context and previous interactions.
- Agents might also require access to the Environment layer to interface with external systems such as browsers (which use cookie management), Docker (for containerized execution), or TCP server components.
- The Tools module supports both agents and workflows by providing auxiliary functions and utilities.
- Finally, illustrate how external dependencies (LLM API endpoints for OpenAI, Anthropic, etc.) feed into the agent’s decision-making process. Indicate API keys management (configured via .env) and the integration with Docker (auto-pull image) as external service links.

##### Architectural patterns
- Modular Design: The separation into “agents”, “environment”, “flow”, “memory”, etc., clearly demonstrates a modular architecture where each component is well-isolated.
- Extensibility: The use of components like plugins (in the Tools module) and workflows illustrate design principles geared towards scalability and extensibility.
- Workflow Orchestration: The Flow module is a central orchestration layer that connects user commands, agents, memory, environment, and external services.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% User Interface Layer
    subgraph "User Interface"
        UI_CLI("CLI Interface"):::interface
        UI_REPL("REPL Interface"):::interface
    end

    %% Core Orchestration (Flow Module)
    subgraph "Core Orchestration (Flow Module)"
        F_Broker("Broker"):::orchestration
        F_Core("Core"):::orchestration
        F_Dynamic("Dynamic Routing"):::orchestration
        F_Types("Types"):::orchestration
        F_Utils("Utils"):::orchestration
    end

    %% Agents Layer
    subgraph "Agents"
        A_FS("FileSurfer Agent"):::agent
        A_PR("Programming Agent"):::agent
        A_ST("System Triage Agent"):::agent
        A_WS("Websurfer Agent"):::agent
    end

    %% Memory Module
    subgraph "Memory Module"
        M_Code("Code Memory"):::memory
        M_Parser("Code Parser"):::memory
        M_CodeTree("Code Tree Memory"):::memory
        M_Paper("Paper Memory"):::memory
        M_RAG("RAG Memory"):::memory
        M_Tool("Tool Memory"):::memory
        M_Utils("Memory Utils"):::memory
    end

    %% Environment Module
    subgraph "Environment Module"
        ENV_Browser("Browser Environment"):::environment
        ENV_Docker("Docker Environment"):::environment
        ENV_Local("Local Environment"):::environment
        ENV_TCP("TCP Server (Env)"):::environment
        ENV_Markdown("Markdown Browser"):::environment
    end

    %% Tools Module
    subgraph "Tools Module"
        T_Dummy("Dummy Tool"):::tools
        T_FileSurfer("FileSurfer Tool"):::tools
        T_Terminal("Terminal Tools"):::tools
    end

    %% Server & TCP Components
    subgraph "Server & Network"
        S_Server("Server Component"):::external
        S_TCP("TCP Server"):::external
    end

    %% External Integrations
    subgraph "External Integration"
        Ext_LLM("LLM Providers"):::external
        Ext_Docker("Docker Hub"):::external
    end

    %% Workflows Module
    subgraph "Workflows"
        WF("Workflows"):::orchestration
    end

    %% Configuration / Infrastructure
    subgraph "Configuration"
        C_ENV(".env.template"):::config
        C_SETUP("setup.cfg"):::config
        C_PY("pyproject.toml"):::config
        C_MANIFEST("MANIFEST.in"):::config
    end

    %% Connections
    UI_CLI -->|"commands"| F_Core
    UI_REPL -->|"commands"| F_Core

    F_Core -->|"orchestrates"| A_FS
    F_Core -->|"orchestrates"| A_PR
    F_Core -->|"orchestrates"| A_ST
    F_Core -->|"orchestrates"| A_WS

    F_Core -->|"calls"| T_Dummy
    F_Core -->|"calls"| T_FileSurfer
    F_Core -->|"calls"| T_Terminal

    F_Core -->|"routes"| WF

    A_FS -->|"context access"| M_Code
    A_FS -->|"context access"| M_Parser
    A_PR -->|"context access"| M_CodeTree
    A_ST -->|"context access"| M_Paper
    A_WS -->|"context access"| M_RAG
    A_WS -->|"context access"| M_Tool
    A_WS -->|"uses"| M_Utils

    A_FS -->|"external calls"| ENV_Browser
    A_PR -->|"external calls"| ENV_Docker
    A_ST -->|"external calls"| ENV_Local
    A_WS -->|"external calls"| ENV_TCP
    A_WS -->|"external calls"| ENV_Markdown

    S_Server ---|"network interface"| UI_CLI
    S_TCP ---|"communication"| S_Server

    F_Core -->|"API calls"| Ext_LLM
    ENV_Docker -->|"container pull"| Ext_Docker

    %% Click Events
    click A_FS "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/agents/filesurfer_agent.py"
    click A_PR "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/agents/programming_agent.py"
    click A_ST "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/agents/system_triage_agent.py"
    click A_WS "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/agents/websurfer_agent.py"
    
    click ENV_Browser "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/environment/browser_env.py"
    click ENV_Docker "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/environment/docker_env.py"
    click ENV_Local "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/environment/local_env.py"
    click ENV_TCP "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/environment/tcp_server.py"
    click ENV_Markdown "https://github.com/hkuds/auto-deep-research/tree/main/autoagent/environment/markdown_browser"
    
    click F_Broker "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/flow/broker.py"
    click F_Core "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/flow/core.py"
    click F_Dynamic "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/flow/dynamic.py"
    click F_Types "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/flow/types.py"
    click F_Utils "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/flow/utils.py"
    
    click M_Code "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/memory/code_memory.py"
    click M_Parser "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/memory/code_tree/code_parser.py"
    click M_CodeTree "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/memory/codetree_memory.py"
    click M_Paper "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/memory/paper_memory.py"
    click M_RAG "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/memory/rag_memory.py"
    click M_Tool "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/memory/tool_memory.py"
    click M_Utils "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/memory/utils.py"
    
    click T_Dummy "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/tools/dummy_tool.py"
    click T_FileSurfer "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/tools/file_surfer_tool.py"
    click T_Terminal "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/tools/terminal_tools.py"
    
    click UI_CLI "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/cli.py"
    click UI_REPL "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/repl/repl.py"
    
    click S_Server "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/server.py"
    click S_TCP "https://github.com/hkuds/auto-deep-research/blob/main/autoagent/tcp_server.py"
    
    click WF "https://github.com/hkuds/auto-deep-research/tree/main/autoagent/workflows"
    
    click C_ENV "https://github.com/hkuds/auto-deep-research/blob/main/.env.template"
    click C_SETUP "https://github.com/hkuds/auto-deep-research/blob/main/setup.cfg"
    click C_PY "https://github.com/hkuds/auto-deep-research/blob/main/pyproject.toml"
    click C_MANIFEST "https://github.com/hkuds/auto-deep-research/blob/main/MANIFEST.in"

    %% Styles
    classDef interface fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef orchestration fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef agent fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef memory fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef environment fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef tools fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef external fill:#fadbd8,stroke:#333,stroke-width:2px;
    classDef config fill:#d0ece7,stroke:#333,stroke-width:2px;
```
