# modu-ai/moai-adk architecture

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

- Interactive diagram: https://gitdiagram.com/modu-ai/moai-adk
- Repository: https://github.com/modu-ai/moai-adk

## Overview

The MoAI-ADK project is an open-source, Python-based CLI framework that orchestrates AI agents in a SPEC-First TDD workflow. Its architecture can be broken down into the following high-level components:

##### User & CLI Layer
- User invokes commands (`moai-adk`, `/moai:1-plan`, `/moai:2-run`, `/moai:3-sync`) via a shell
- CLI module (`src/moai_adk/cli/*`) parses commands and forwards them to the Core Engine

##### Core Engine (Mr. Alfred Orchestrator)
- Command Dispatcher & Context Manager (`command_helpers.py`, `context_manager.py`)
- Phase Executor (`phase_executor.py`): implements Plan → Run → Sync loop
- Integration Layer (`integration/engine.py`): interfaces with LLMs (Claude Code) and MCP servers
- Hook & Plugin Manager (`core/hooks/*`, `.claude/hooks/*`): pre- and post-tool hooks

##### Agents & Skills
- Agents (`.claude/agents/moai/*.md` + generated via `builder-agent`) perform specialized tasks (SPEC writing, TDD, docs, quality, domain experts)
- Skills (`.claude/skills/moai-*` + Python skill modules) provide knowledge bases and patterns
- The Orchestrator dynamically loads agents/skills via the “modular system”

##### Configuration, Memory & Specs
- Config files (`.moai/config/*.json`, `.claude/settings.json`, `pyproject.toml`)
- Project memory (`.moai/memory/last-session-state.json`)
- SPEC docs (`.moai/specs/SPEC-*/spec.md`)
- Templates (`src/moai_adk/templates`, `.claude/output-styles`, `.claude/skills/*/modules`)

##### Output & Documentation
- Code artifacts: source (`src/moai_adk`), tests (`tests/`), hooks, scripts

##### External Integrations
- LLM service (Claude via CLI or API)
- MCP servers (`.mcp.json`): Context7 (docs lookup), Sequential-Thinking (complex reasoning), Playwright (E2E), Figma, Nano-Banana (image gen)
- Git & CI/CD (GitHub Actions workflows in `.github/workflows/`)

##### Testing & Quality
- Unit, integration, e2e, statusline, shell, hooks tests under `tests/`
- TRUST 5 quality checks automated by `manager-quality` agent

1. User & CLI (blue rectangle)
2. Core Engine / Mr. Alfred (green hexagon)
– Subcomponents: Command Parser, Phase Executor, Hook Manager, Integration Engine
3. Agents (orange circles) & Skills (orange hexagons)
5. Specs & Templates (gray documents)
6. File System (gray folder)
7. External Services (purple clouds): LLM, MCP servers, GitHub

- User → CLI → Core Engine
- Core Engine → Agents/Skills
- Agents/Skills → Core Engine (results)
- Core Engine ↔ LLM/MCP (API calls)
- Core Engine → File System (read/write specs, memory, config, code, docs)
- Core Engine → External Git/CI for commit, PR creation

C. Highlight Architectural Patterns
- Mediator (Mr. Alfred orchestrates agents)
- Pipeline (Plan → Run → Sync phases)
- Plugin/Modular (dynamic agent & skill loading)
- Adapter (integration layer for external LLMs & MCPs)
- Config-Driven (behavior controlled by JSON/YAML settings)

D. Annotate Key Technologies
- Python 3.11+, Typer or Click for CLI
- PyTest for testing
- JSON/YAML for configs & specs
- Markdown for SPECs, Skills, Hooks
- LLM API (Claude Code), MCP server protocols

- As an open-source framework, emphasize extension points: where new agents/skills/hooks can be plugged in.
- “Templates → CLI → Core Engine → Agents/Skills → File System” flow to illustrate how user input leads to spec generation, code, tests, docs.
- 3-phase loop (Plan, Run, Sync) as an inset or small flowchart next to the Core Engine.

- Clear labels on every component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & CLI Layer
    User["User (Shell)"]:::user
    CLI["CLI Module"]:::cli
    User --> CLI

    %% Core Engine
    subgraph "Core Engine (Mr. Alfred Orchestrator)"
        direction TB
        Dispatcher["Command Dispatcher"]:::core
        ContextManager["Context Manager"]:::core
        PhaseExecutor["Phase Executor\n(Plan→Run→Sync)"]:::core
        subgraph "Integration Layer"
            direction TB
            IntegrationEngine["Engine"]:::core
            IntegrationModels["Models"]:::core
        end
        subgraph "Hook & Plugin Manager"
            direction TB
            CoreHooks["Core Hooks"]:::core
            ClaudeHooks["Claude Hooks"]:::core
        end
    end
    CLI --> Dispatcher
    Dispatcher --> PhaseExecutor
    PhaseExecutor --> IntegrationEngine
    IntegrationEngine --> CoreHooks
    CoreHooks --> ClaudeHooks

    %% Agents & Skills
    subgraph "Agents & Skills"
        direction TB
        Agents["Agents"]:::agents
        Skills["Skills"]:::skills
    end
    PhaseExecutor --> Agents
    PhaseExecutor --> Skills
    Agents --> ContextManager
    Skills --> ContextManager

    %% Storage: Config, Memory, Specs, Templates
    subgraph "Storage"
        direction TB
        CLIConfig["CLI Config"]:::storage
        ClaudeSettings["Claude Settings"]:::storage
        ProjectConfig["Project Config"]:::storage
        Memory["Session Memory"]:::storage
        Specs["SPEC Documents"]:::storage
        TemplatesBuilt["Built-in Templates"]:::storage
        TemplatesFS["FS Templates"]:::storage
    end
    Dispatcher --> CLIConfig
    Dispatcher --> ClaudeSettings
    Dispatcher --> ProjectConfig
    ContextManager --> Memory
    PhaseExecutor --> Specs
    PhaseExecutor --> TemplatesBuilt
    PhaseExecutor --> TemplatesFS

    %% External Integrations
    subgraph "External Services"
        direction TB
        LLM["LLM Service"]:::external
        MCP["MCP Servers"]:::external
        GitCI["Git & CI/CD"]:::external
    end
    IntegrationEngine <--> LLM
    IntegrationEngine <--> MCP
    CoreHooks --> GitCI

    %% Testing & Quality
    subgraph "Testing & Quality"
        direction TB
        TestsDir["Tests Suite"]:::testing
        Quality["Quality Manager"]:::testing
    end
    PhaseExecutor --> TestsDir
    CoreHooks --> Quality

    %% Click Events
    click CLI "https://github.com/modu-ai/moai-adk/tree/main/src/moai_adk/cli/"
    click Dispatcher "https://github.com/modu-ai/moai-adk/blob/main/src/moai_adk/core/command_helpers.py"
    click ContextManager "https://github.com/modu-ai/moai-adk/blob/main/src/moai_adk/core/context_manager.py"
    click PhaseExecutor "https://github.com/modu-ai/moai-adk/blob/main/src/moai_adk/core/project/phase_executor.py"
    click IntegrationEngine "https://github.com/modu-ai/moai-adk/blob/main/src/moai_adk/core/integration/engine.py"
    click IntegrationModels "https://github.com/modu-ai/moai-adk/blob/main/src/moai_adk/core/integration/models.py"
    click CoreHooks "https://github.com/modu-ai/moai-adk/tree/main/src/moai_adk/core/hooks/"
    click ClaudeHooks "https://github.com/modu-ai/moai-adk/tree/main/.claude/hooks/moai/"
    click Agents "https://github.com/modu-ai/moai-adk/tree/main/.claude/agents/moai/"
    click Skills "https://github.com/modu-ai/moai-adk/tree/main/.claude/skills/"
    click CLIConfig "https://github.com/modu-ai/moai-adk/tree/main/.moai/config/"
    click ClaudeSettings "https://github.com/modu-ai/moai-adk/blob/main/.claude/settings.json"
    click ProjectConfig "https://github.com/modu-ai/moai-adk/blob/main/pyproject.toml"
    click Memory "https://github.com/modu-ai/moai-adk/blob/main/.moai/memory/last-session-state.json"
    click Specs "https://github.com/modu-ai/moai-adk/tree/main/.moai/specs/"
    click TemplatesBuilt "https://github.com/modu-ai/moai-adk/tree/main/src/moai_adk/templates/.claude/"
    click TemplatesFS "https://github.com/modu-ai/moai-adk/tree/main/src/moai_adk/templates/"
    click MCP "https://github.com/modu-ai/moai-adk/blob/main/.mcp.json"
    click GitCI "https://github.com/modu-ai/moai-adk/tree/main/.github/workflows/"
    click TestsDir "https://github.com/modu-ai/moai-adk/tree/main/tests/"
    click Quality "https://github.com/modu-ai/moai-adk/tree/main/src/moai_adk/core/quality/"

    %% Styles
    classDef user fill:#cce5ff,stroke:#004085
    classDef cli fill:#b8daff,stroke:#004085
    classDef core fill:#d4edda,stroke:#155724
    classDef agents fill:#fff3cd,stroke:#856404
    classDef skills fill:#fff3cd,stroke:#856404
    classDef storage fill:#e2e3e5,stroke:#6c757d
    classDef external fill:#f5c6cb,stroke:#721c24
    classDef testing fill:#d1ecf1,stroke:#0c5460
```
