# tinghaii/metagpt architecture

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

- Interactive diagram: https://gitdiagram.com/tinghaii/metagpt
- Repository: https://github.com/tinghaii/metagpt

## Overview

##### Project Type & Purpose
- Recognize that MetaGPT is a full-stack, multi-agent framework designed to take a one-line requirement from a user and then generate an entire software project (including user stories, requirements, APIs, documents, etc.).
- Its key aim is to emulate a software company by assigning roles (e.g., architects, project managers, engineers) using LLMs that collaborate through well-defined SOP (standard operating procedures).

##### Analyzing the File Structure
- Notice core directories such as “metagpt”, “config”, “docs”, “examples”, “tests”, and “.github”. The “metagpt” directory houses most of the core functionality (agents, roles, memory, actions, skills, strategies, tools, etc.).
- There are also rich submodules for environments (e.g., “android”, “minecraft”, “werewolf”, “stanford_town”, etc.), indicating support for varied simulation environments.
- The “config” folder holds configuration files (like YAMLs) important for defining LLM settings and system parameters.

##### Identifying Main Components
- Front-end/CLI Interface: The command-line interface and possibly a web UI (as hinted by the Chainlit example) used for user input.
- Core Engine (metagpt package): This includes modules for:
- Agent orchestration: Components in “metagpt/actions”, “metagpt/roles”, and “metagpt/strategy” handle the task breakdown, role management, and plan execution.
- Memory & Document Store: “metagpt/memory” and “metagpt/document_store” manage state, long-term memory, and document representations.
- Configuration & Initialization: “config/config2.yaml” guides system setup and integration with various LLM providers.
- External Providers & Integrations:
- LLM Providers: Modules under “metagpt/provider” (e.g., OpenAI, Anthropic, Azure, Ollama, etc.) which interact with language model APIs.
- Environment Adapters: In “metagpt/environment” (including integrations for Android, Minecraft, etc.) which simulate or interact with external systems.
- Skills & Tools: Found under “metagpt/skills” and “metagpt/tools”, these provide specialized functionalities (e.g., Summarize, WriterSkill, image processing, code generation).
- Workflow and Experimentation: There are sections related to “exp_pool” that likely manage experiment flows and collaborative problem-solving.

##### Relationships & Interactions
- Flow starting from the user’s input at the CLI or API interface, triggering the main engine.
- Detail how the engine decomposes the input (via requirement analysis and planning modules) and dispatches tasks to dedicated agents (roles like architect, engineer, project manager).

##### Architectural Patterns and Design Principles
- Multi-agent paradigm with clearly delineated roles – use grouped modules to represent “Engine”, “Roles”, “Agents”, “Memory”, and “External Tools/Providers”.
- Modularity: separate components for planning (strategies), execution (actions), and output (document generation, repo building).
- Demonstrate data flow loops showing iterative improvement: e.g., plan-review, action feedback, and memory updates.
- That configurations (via YAML files) and containerization scripts (Dockerfile, .devcontainer) also indicate deployment strategies and environmental isolation.

##### Relevant Technologies & Frameworks
- Python (core programming language)
- Node and PNPM (for some UI components and possibly frontend pipelines)
- Integration with external APIs (LLM providers: OpenAI, Anthropic, etc.)
- Tools for orchestration such as GitHub Actions (CI/CD pipelines found under “.github/workflows”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: User Interface
    UI["CLI/Web UI"]:::ui

    %% Middle Layer: Core Engine
    subgraph "Core Engine"
        %% Agent Orchestration Subcomponent
        subgraph "Agent Orchestration"
            Act["Actions"]:::engine
            Rol["Roles"]:::engine
            Strat["Strategy"]:::engine
        end

        MEM["Memory"]:::engine
        DS["Document Store"]:::engine
        CONF["Configuration"]:::config
        SKL["Skills"]:::engine
        TOL["Tools"]:::engine
        EXP["Experimentation"]:::engine
        EXPEx["Exp Examples"]:::engine
    end

    %% Bottom Layer: External Integrations
    subgraph "External Integrations"
        LLM["LLM Providers"]:::integration
        ENV["Environment Adapters"]:::integration
    end

    %% Data Flow Connections
    UI -->|"input"| Act
    UI -->|"config_request"| CONF

    CONF -->|"setup"| Act
    CONF -->|"setup"| Strat
    CONF -->|"setup"| Rol

    Act -->|"dispatch"| Rol
    Strat -->|"plan"| Rol
    Strat -->|"review_feedback"| Act

    Act -->|"store_output"| MEM
    MEM -->|"persist"| DS

    Act -->|"invoke_skill"| SKL
    Act -->|"invoke_tool"| TOL

    %% External Provider interactions
    Act -->|"api_call"| LLM
    LLM -->|"response"| Act

    Act -->|"trigger"| ENV
    ENV -->|"feedback"| Act

    %% Experimentation interactions
    Strat -->|"experiment"| EXP
    EXP -->|"result_feedback"| Strat
    EXP -->|"example_ref"| EXPEx
    EXPEx -->|"review"| Rol

    %% Roles update loop
    Rol -->|"update_memory"| MEM

    %% Click Events
    click UI "https://github.com/tinghaii/metagpt/tree/main/examples/ui_with_chainlit/"
    click Act "https://github.com/tinghaii/metagpt/tree/main/metagpt/actions/"
    click Rol "https://github.com/tinghaii/metagpt/tree/main/metagpt/roles/"
    click Strat "https://github.com/tinghaii/metagpt/tree/main/metagpt/strategy/"
    click MEM "https://github.com/tinghaii/metagpt/tree/main/metagpt/memory/"
    click DS "https://github.com/tinghaii/metagpt/tree/main/metagpt/document_store/"
    click CONF "https://github.com/tinghaii/metagpt/blob/main/config/config2.yaml"
    click LLM "https://github.com/tinghaii/metagpt/tree/main/metagpt/provider/"
    click ENV "https://github.com/tinghaii/metagpt/tree/main/metagpt/environment/"
    click SKL "https://github.com/tinghaii/metagpt/tree/main/metagpt/skills/"
    click TOL "https://github.com/tinghaii/metagpt/tree/main/metagpt/tools/"
    click EXP "https://github.com/tinghaii/metagpt/tree/main/metagpt/exp_pool/"
    click EXPEx "https://github.com/tinghaii/metagpt/tree/main/examples/exp_pool/"

    %% Styles
    classDef ui fill:#a2d9ce,stroke:#2e4053,stroke-width:2px;
    classDef engine fill:#f7dc6f,stroke:#935116,stroke-width:2px;
    classDef integration fill:#fad7a0,stroke:#784212,stroke-width:2px;
    classDef config fill:#aec6cf,stroke:#355070,stroke-width:2px;
```
