# conradlog/openmanus architecture

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

- Interactive diagram: https://gitdiagram.com/conradlog/openmanus
- Repository: https://github.com/conradlog/openmanus

## Overview

##### Main Components
- Core Engine & Entry Points: Show the entry scripts (main.py, run_flow.py, run_mcp.py) that initialize and orchestrate the application.
- Agent Module: Represent the “app/agent” package with its various specialized agent classes (browser, cot, planning, react, etc.). This is the backbone for agent behaviors.
- Flow Management: Indicate the "app/flow" package that seems responsible for governing multi-step processes (including planning flows) and integrating agents.
- Prompt Handling: Emphasize the “app/prompt” package, which mirrors the agent functionalities (browser, planning, etc.) to generate or manage prompts.
- Tools & Utilities: Include the “app/tool” folder (with submodules for bash, search, file operators, etc.) and any auxiliary modules (like logger, exceptions, and schema) as utility components that support diverse agent operations.
- MCP Server: Illustrate the “app/mcp” package and associated server module, representing a control plane for managing or interfacing with agents.
- Sandbox Environment: Represent “app/sandbox” and its subdirectories as the isolated execution environment, ensuring safe operations for potentially untrusted code.
- External Services and Dependencies: Include external LLM APIs (configured via the TOML file), optional browser automation via Playwright, and possibly logging or monitoring services.

##### Relationships and Interactions
- That the Tools & Utilities are “injected” or invoked by agents across modules (for file operations, browsing actions, search functions, etc.).
- Demonstrate how the MCP server (inside app/mcp) connects with both agents and external clients.
- That the Sandbox environment isolates certain tool operations, with interconnections to agent flows when a secure, managed execution is required.
- Configuration as a central dependency used by nearly all components to retrieve settings and API keys for LLM operations.

##### Architectural Patterns and Design Principles
- Modular Design & Separation of Concerns: The clear division between agent behaviors, flow control, prompt generation, sandboxing, and tooling illustrates a separation of concerns.
- Reusability & Extensibility: Notice the parallel structure in “app/agent” and “app/prompt,” which suggests an intention for interchangeable or pluggable components.
- Layered Architecture: The system moves from external interface (CLI entry points) through business logic (agent and flow modules) down to system services (tools, config, logs).
- Potential for Microservices–Style Isolation: Although it’s largely a monolithic codebase, components like the MCP server and sandbox could eventually be separated into services if needed.

##### Technologies, Frameworks, and Libraries
- Python is the primary language, with package management handled via uv (or conda/virtualenv).
- Docker (Dockerfile provided) indicates containerization is supported.
- External integration with LLM APIs (such as OpenAI) is configured via TOML files.
- Optional browser automation is achieved with Playwright.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: User Interaction
    U("User Input (Terminal/Webhook)"):::user

    %% Core Engine & Entry Points
    subgraph "Core Engine"
        EP1("main.py"):::entry
        EP2("run_flow.py"):::entry
        EP3("run_mcp.py"):::entry
        EP4("run_mcp_server.py"):::entry
    end

    U -->|"initiate"| EP1
    U -->|"initiate"| EP2
    U -->|"initiate"| EP3
    U -->|"initiate"| EP4

    %% Middle Layer: Core Modules
    subgraph "Core Modules"
        AM("Agent Module"):::core
        FM("Flow Management"):::core
        PH("Prompt Handling"):::core
    end

    EP1 -->|"dispatch"| AM
    EP1 -->|"dispatch"| FM
    EP1 -->|"dispatch"| PH

    %% Lower Layer: Support Services
    subgraph "Support Services"
        TU("Tools & Utilities"):::utility
        MCP("MCP Server"):::mcp
        SB("Sandbox Environment"):::sandbox
        CFG("Configuration"):::config
        EXTS("External Services (LLM APIs, Playwright)"):::external
    end

    %% Interactions between Core Modules and Support Services
    AM -->|"invokes"| TU
    FM -->|"uses"| PH
    AM -->|"securedAction"| SB
    TU -->|"requires"| CFG
    FM -->|"requires"| CFG
    PH -->|"requires"| CFG
    AM -->|"requires"| CFG
    MCP -->|"interfaces"| AM
    MCP -->|"interfaces"| EXTS
    CFG -->|"supplies"| EXTS
    TU -->|"calls"| EXTS

    %% Click Events for Component Mappings
    click EP1 "https://github.com/conradlog/openmanus/blob/main/main.py"
    click EP2 "https://github.com/conradlog/openmanus/blob/main/run_flow.py"
    click EP3 "https://github.com/conradlog/openmanus/blob/main/run_mcp.py"
    click EP4 "https://github.com/conradlog/openmanus/blob/main/run_mcp_server.py"
    click AM "https://github.com/conradlog/openmanus/tree/main/app/agent/"
    click FM "https://github.com/conradlog/openmanus/tree/main/app/flow/"
    click PH "https://github.com/conradlog/openmanus/tree/main/app/prompt/"
    click TU "https://github.com/conradlog/openmanus/tree/main/app/tool/"
    click MCP "https://github.com/conradlog/openmanus/tree/main/app/mcp/"
    click SB "https://github.com/conradlog/openmanus/tree/main/app/sandbox/"
    click CFG "https://github.com/conradlog/openmanus/tree/main/config/"

    %% Styles
    classDef user fill:#c2f0c2,stroke:#333,stroke-width:2px;
    classDef entry fill:#f0d9ff,stroke:#333,stroke-width:2px;
    classDef core fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef utility fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef mcp fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef sandbox fill:#ffebcd,stroke:#333,stroke-width:2px;
    classDef config fill:#fdfd96,stroke:#333,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
