# nvtam2105/openmanus architecture

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

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

## Overview

##### Main Components
- Main Entrypoints:
– “main.py” and “run_flow.py” serve as the orchestration scripts that kick off the agent’s processes.
- Application Core (“app” Directory):
– Agent Module (app/agent): Contains various strategies such as “base”, “manus”, “planning”, “react”, “swe”, and “toolcall.” These submodules indicate that the agent follows different decision-making or behavioral strategies.
– Flow Module (app/flow): Likely manages the decision workflow with files such as “flow_factory.py” and “planning.py.” It coordinates high‑level planning flows.
– Prompt Module (app/prompt): Contains templates or methods for generating prompts (e.g., “manus”, “planning”, “swe”, “toolcall”) to interact with LLMs.
– Tool Module (app/tool): Offers a collection of tools that can be used by the agent. Each file (bash, browser_use_tool, create_chat_completion, file_saver, google_search, python_execute, etc.) represents an external functionality that the agent might call to extend its capabilities.
– Other Core Modules: “llm.py” to manage LLM integration, “config.py” for reading configuration settings, “exceptions.py” for error handling, “logger.py” for application logging, and “schema.py” likely for data schema definitions.
- Configuration & Deployment:
– The “config” directory contains configuration examples (config.toml) which define global LLM settings (e.g., API keys, model configurations).
– There are several GitHub workflows, pre-commit hooks, and setup/build scripts (setup.py, requirements.txt) that support CI/CD and deployment.

##### Relationships and Interactions
- The Main Entrypoints (main.py, run_flow.py) initialize the application environment and load the configuration.
- The “app/config.py” reads the config (from a user‑provided config.toml) and shares runtime settings with all components.
- The Agent Module dispatches work among submodules: the “planning” and “react” files indicate that agents evaluate user input and choose an appropriate agent strategy.
- The Flow Module coordinates more complex workflows for sequential or conditional decisions—acting like an orchestrator for agent actions.
- The Prompt Module dynamically generates the prompts sent to the LLM, leveraging prepared templates.
- The LLM Module (“llm.py”), in combination with the configuration settings, interacts with an external LLM API (like OpenAI’s API) to process text and generate responses.
- The Tool Module includes integrations for calling external tools (e.g., executing bash commands, performing a Google search, running python code, etc.) whenever the agent decides that an external action is needed.
- Logging and exception handling are essential cross‑cutting concerns managed by “app/logger.py” and “app/exceptions.py.”

##### Architectural Patterns and Design Principles
- Modular Design: The clear separation into agent, flow, prompt, and tool modules points to a modular architecture, where each component handles a specific responsibility.
- Extensibility: With separate “tool” and “prompt” modules, it’s easy to plug in new functionalities and handle new types of tasks.
- Configuration Driven: The use of toml configuration files suggests a design that externalizes environment and API-specific settings.

##### Relevant Technologies and Frameworks
- Python – the primary language, with dependency management via pip or uv.
- LLM APIs – external calls defined in “config/config.example.toml.”
- Community and CI/CD tools – evidenced by GitHub workflows, pre-commit hooks, and similar automation scripts.
- Modular architecture may also indicate using patterns similar to MVC where “agent” functionality encapsulates business logic and “flow” or “prompt” generation corresponds to the controller side.

##### Instructing the Principal Software Engineer
– Agent Module (with subcomponents: planning, react, toolcall, etc.)
– Flow Module (orchestrating agent tasks)
– Prompt Module (delegating prompt templates for LLM calls)
– Tool Module (multiple tool integrations)
– LLM Integration (showing configuration-driven API calls)
- A configuration block showing how API keys and model settings are loaded and shared.
– How the main application initializes the configuration and passes input to the agent module.
– The decision path from agent selection (planning or reaction) to tool calls or LLM queries.
– The feedback loop from LLM responses back into agent logic.

Happy Diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    Client["Client/Terminal"]:::client
    Entrypoint["Main Entrypoints (main.py & run_flow.py)"]:::entrypoint

    %% Configuration Nodes
    ConfigPy["Configuration (config.py)"]:::config
    ConfigToml["Configuration (config.example.toml)"]:::config

    %% Application Core Subgraph
    subgraph "Application Core"
        Agent["Agent Module"]:::agent
        FlowMod["Flow Module"]:::flow
        Prompt["Prompt Module"]:::prompt
        Tool["Tool Module"]:::tool
        LLM["LLM Integration"]:::llm
    end

    %% Cross-cutting Support Components
    subgraph "Support Components"
        Logger["Logger (logger.py)"]:::logger
        Exception["Exception Handling (exceptions.py)"]:::exception
        Schema["Schema Definitions (schema.py)"]:::schema
    end

    %% Data Flow
    Client -->|"submit_idea"| Entrypoint
    Entrypoint -->|"load_config"| ConfigPy
    Entrypoint -->|"load_config"| ConfigToml

    ConfigPy -->|"provide_settings"| Agent
    ConfigToml -->|"provide_settings"| Agent

    ConfigPy -->|"provide_settings"| FlowMod
    ConfigToml -->|"provide_settings"| FlowMod

    ConfigPy -->|"provide_settings"| Prompt
    ConfigToml -->|"provide_settings"| Prompt

    ConfigPy -->|"provide_settings"| LLM
    ConfigToml -->|"provide_settings"| LLM

    Entrypoint -->|"dispatch_input"| Agent

    Agent -->|"orchestrates"| FlowMod
    Agent -->|"orchestrates"| Prompt
    Agent -->|"invoke_tool"| Tool
    Agent -->|"query_LLM"| LLM

    LLM -->|"response"| Agent
    Prompt -->|"generate_prompts"| LLM
    FlowMod -->|"coordinate_task"| Agent
    Tool -->|"external_action"| Agent

    %% Support relationships (aggregated)
    Agent --- Logger
    Agent --- Exception
    Agent --- Schema

    FlowMod --- Logger
    FlowMod --- Exception
    FlowMod --- Schema

    Prompt --- Logger
    Prompt --- Exception
    Prompt --- Schema

    Tool --- Logger
    Tool --- Exception
    Tool --- Schema

    LLM --- Logger
    LLM --- Exception
    LLM --- Schema

    ConfigPy --- Logger
    ConfigToml --- Logger

    %% Click Events for Component Mapping
    click Entrypoint "https://github.com/nvtam2105/openmanus/blob/main/main.py"
    click Entrypoint "https://github.com/nvtam2105/openmanus/blob/main/run_flow.py"
    click Agent "https://github.com/nvtam2105/openmanus/tree/main/app/agent"
    click FlowMod "https://github.com/nvtam2105/openmanus/tree/main/app/flow"
    click Prompt "https://github.com/nvtam2105/openmanus/tree/main/app/prompt"
    click Tool "https://github.com/nvtam2105/openmanus/tree/main/app/tool"
    click LLM "https://github.com/nvtam2105/openmanus/blob/main/app/llm.py"
    click ConfigPy "https://github.com/nvtam2105/openmanus/blob/main/app/config.py"
    click ConfigToml "https://github.com/nvtam2105/openmanus/blob/main/config/config.example.toml"
    click Logger "https://github.com/nvtam2105/openmanus/blob/main/app/logger.py"
    click Exception "https://github.com/nvtam2105/openmanus/blob/main/app/exceptions.py"
    click Schema "https://github.com/nvtam2105/openmanus/blob/main/app/schema.py"

    %% Styles
    classDef client fill:#FDF6E3,stroke:#B58900,stroke-width:2px;
    classDef entrypoint fill:#EEE8D5,stroke:#657B83,stroke-width:2px;
    classDef config fill:#FFD700,stroke:#8B8000,stroke-width:2px;
    classDef agent fill:#FFB6C1,stroke:#C71585,stroke-width:2px;
    classDef flow fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef prompt fill:#AFEEEE,stroke:#4682B4,stroke-width:2px;
    classDef tool fill:#FFE4B5,stroke:#CD853F,stroke-width:2px;
    classDef llm fill:#FFC0CB,stroke:#DB7093,stroke-width:2px;
    classDef logger fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px;
    classDef exception fill:#FFF0F5,stroke:#D87093,stroke-width:2px;
    classDef schema fill:#F0F8FF,stroke:#4682B4,stroke-width:2px;
    classDef support fill:#D3D3D3,stroke:#696969,stroke-width:2px;
```
