# iheytang/openmanus architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, multi-tenant AI assistant platform (“OpenManus”) comprising:
- A Python “Core” service (app/…, run_api.py) that hosts REST APIs, orchestrates AI agents, manages long-running tasks, sandboxes, and LLM calls.
- A Next.js “App” (web/) providing user authentication, the UI, and Prisma-backed persistence to PostgreSQL.

##### File structure
- Top level:
- app/ → Python modules: agent, flow, prompt, sandbox, apis (routes + services), mcp, container, llm interface, memory, logger, schema.
- run_api.py / main.py → Entry points for Python service using FastAPI or equivalent.
- web/ → Next.js (React) with App Router, serverless routes under web/src/app/api, Prisma schema, UI components, i18n.
- config/, Dockerfile(s), docker-compose.yml → Deployment.
- Tests target sandbox client/manager and core logic.

##### Extract README insights
- Two-part install: “Core” (Python) and “App” (Node/Next.js).
- PostgreSQL for persistence.
- Prisma used in web/.
- LLM integrations pluggable via config files.
- Docker Compose brings up core, web, and DB.

##### Main components
a. User Interface (Next.js Frontend)
b. Web API Layer (Next.js serverless routes + Prisma ORM)
c. Core API Service (Python FastAPI)
d. Task & Agent Orchestrator (Python modules: flow, agent, prompt)
e. Sandbox / Container Manager (app/sandbox + Docker engine)
f. Data Store (PostgreSQL)
g. External Services (LLM providers, Playwright browsers)

##### Component interactions
- UI → Web API (HTTP/REST) for login, tasks, workspace browsing.
- Web API → PostgreSQL (Prisma queries) for user, workspace, task metadata.
- Web API → Core API (HTTP/REST or RPC) to launch new tasks or query status.
- Core API → Sandbox Manager (via Docker SDK or local calls) to run code/tools securely.
- Core API → LLM Interface → External APIs (OpenAI, Anthropic, Azure, Google) for model calls.
- Core API services (file_monitor, task_manager, workspace) persist state back to PostgreSQL (if used by Python) or signal Web API.

##### Architectural patterns & design principles
- Layered architecture in Python:
- API layer (FastAPI routes)
- Service layer (task_manager, file_monitor, workspace)
- Domain layer (agent, flow, prompt)
- Infrastructure layer (sandbox, container, llm)
- Next.js App Router for co‐located UI + server‐side routes.
- “Separation of concerns” between Core (AI orchestration) and App (user management, UI).
- Docker Compose to decouple services and enable reproducible environments.

##### Technologies & frameworks to annotate
- Python 3.12, FastAPI (presumed), uv for package management
- Docker, Docker Compose
- Next.js (React), TypeScript, Prisma ORM
- PostgreSQL
- Playwright for browser automation
- LLM SDKs (OpenAI, Anthropic, etc.)
- i18n (yaml/json translations)
- uvicorn/gunicorn for Python service
- Pre-commit, GitHub Actions for CI

- Components above.
- Data flows with arrowheads and labels.
- Frameworks (FastAPI, Next.js, Prisma).
- Detail the Docker Compose orchestration (three containers).
- Don’t omit the sandbox subsystem (core to safety).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UI["User Interface (Next.js)"]:::frontend
        WebAPI["Web API (Next.js Serverless + Prisma)"]:::frontend
    end

    %% Core Service
    subgraph "Core API Service (Python)"
        direction TB
        CoreEntry["FastAPI Entrypoints"]:::backend

        subgraph "API Layer"
            direction TB
            APIRoutes["Routes & Models"]:::backend
        end

        subgraph "Service Layer"
            direction TB
            FileMon["file_monitor.py"]:::backend
            TaskMan["task_manager.py"]:::backend
            Workspace["workspace.py"]:::backend
        end

        subgraph "Domain Layer"
            direction TB
            Agent["agent"]:::backend
            Flow["flow"]:::backend
            Prompt["prompt"]:::backend
        end

        subgraph "Infrastructure Layer"
            direction TB
            Sandbox["Sandbox Manager"]:::backend
            Container["container/manager.py"]:::backend
            LLMInt["LLM Interface"]:::backend
            Bedrock["bedrock.py"]:::backend
            Memory["memory.py"]:::backend
            MCP["mcp/server.py"]:::backend
            Tools["tool plugins"]:::backend
            Logger["logger & exceptions"]:::backend
        end
    end

    %% Data and External
    DB["PostgreSQL"]:::data
    LLMs["LLM Providers"]:::external
    Playwright["Playwright Browsers"]:::external

    %% Connections
    UI -->|"HTTP/REST"| WebAPI
    WebAPI -->|"SQL (Prisma)"| DB
    WebAPI -->|"HTTP/gRPC"| CoreEntry

    CoreEntry -->|"routes init"| APIRoutes
    APIRoutes -->|"invoke"| FileMon
    APIRoutes -->|"invoke"| TaskMan
    APIRoutes -->|"invoke"| Workspace
    APIRoutes -->|"SQL"| DB

    TaskMan -->|"orchestrates"| Agent
    TaskMan -->|"orchestrates"| Flow
    TaskMan -->|"orchestrates"| Prompt

    Agent -->|"calls"| LLMInt
    LLMInt -->|"HTTPS"| LLMs

    Agent -->|"executes"| Sandbox
    Sandbox -->|"Docker API"| Container
    Sandbox -->|"runs"| Playwright

    %% Click Events
    click UI "https://github.com/iheytang/openmanus/tree/main/web/src/app/…"
    click WebAPI "https://github.com/iheytang/openmanus/tree/main/web/src/app/api/…"
    click WebAPI "https://github.com/iheytang/openmanus/blob/main/web/prisma/schema.prisma"
    click CoreEntry "https://github.com/iheytang/openmanus/blob/main/run_api.py"
    click CoreEntry "https://github.com/iheytang/openmanus/blob/main/main.py"
    click APIRoutes "https://github.com/iheytang/openmanus/blob/main/app/apis/routes/*.py"
    click APIRoutes "https://github.com/iheytang/openmanus/blob/main/app/apis/models/*.py"
    click FileMon "https://github.com/iheytang/openmanus/blob/main/app/apis/services/file_monitor.py"
    click TaskMan "https://github.com/iheytang/openmanus/blob/main/app/apis/services/task_manager.py"
    click Workspace "https://github.com/iheytang/openmanus/blob/main/app/apis/services/workspace.py"
    click Agent "https://github.com/iheytang/openmanus/tree/main/app/agent/…"
    click Flow "https://github.com/iheytang/openmanus/tree/main/app/flow/…"
    click Prompt "https://github.com/iheytang/openmanus/tree/main/app/prompt/…"
    click Sandbox "https://github.com/iheytang/openmanus/tree/main/app/sandbox/…"
    click Container "https://github.com/iheytang/openmanus/blob/main/app/container/manager.py"
    click LLMInt "https://github.com/iheytang/openmanus/blob/main/app/llm.py"
    click Bedrock "https://github.com/iheytang/openmanus/blob/main/app/bedrock.py"
    click Memory "https://github.com/iheytang/openmanus/blob/main/app/memory.py"
    click MCP "https://github.com/iheytang/openmanus/blob/main/app/mcp/server.py"
    click Tools "https://github.com/iheytang/openmanus/tree/main/app/tool/…"
    click Logger "https://github.com/iheytang/openmanus/blob/main/app/logger.py"
    click Logger "https://github.com/iheytang/openmanus/blob/main/app/exceptions.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#888,stroke-width:1px
    classDef backend fill:#D0FFD8,stroke:#888,stroke-width:1px
    classDef data fill:#FFDDA0,stroke:#888,stroke-width:1px
    classDef external fill:#E4CCFF,stroke:#888,stroke-width:1px
```
