# veristamp/agentgovernor architecture

> Architecture diagram of the GitHub repository veristamp/agentgovernor, 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/veristamp/agentgovernor
- Repository: https://github.com/veristamp/agentgovernor

## Overview

##### Project type and purpose
- AgentGovernor is an open-source AI workflow planner (not a classic full-stack web app).
- It implements a Plan–Validate–Execute architecture: LLMs generate declarative plans (YAML), a validator enforces security/auditability, and a deterministic DAG executor runs tasks via microservices.

##### File structure
- Top-level “Agent/” directory: the “brain.” Modules include prompt_builder.py, tool_retriever.py, workflow_retriever.py, plan_validator.py, llm_client.py.
- “mcp_client/” directory: the “hands.” Contains workflow_executor.py (DAG engine), manager.py (connects to MCP servers), plus utility modules.
- “workflows/” folder: stores human-approved PlanYAML examples for RAG.
- Scripts & config at root: run.py (entrypoint), run_planner.py (core planning loop), upsert.py (ingest tools & workflows into Qdrant), mcp_servers.json, tools_schema.json, docker-compose.yml (spins up Qdrant).
- Standalone microservice implementations: filesystem.py, memory.py, terminal.py.

##### README for additional insights
- The README explicitly describes the Plan-Validate-Execute model, the multi-query RAG subsystems (Tool RAG + Workflow RAG), the self-healing loop for RAG and syntax failures, and the DAG executor for parallel steps.
- External dependencies: Qdrant vector DB (via Docker‐Compose), an LLM endpoint (OpenRouter or other).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Swimlane: User & CLI
    subgraph "User & CLI"
        CLI["User / CLI"]:::external
        Run["run.py"]:::control
        Upsert["upsert.py"]:::control
    end

    %% Swimlane: Agent Brain (Control Plane)
    subgraph "Agent Brain"
        Planner["run_planner.py"]:::control
        subgraph "RAG Subsystem"
            TR["ToolRetriever"]:::control
            WR["WorkflowRetriever"]:::control
        end
        PB["PromptBuilder"]:::control
        LLC["LLM Client"]:::control
        PlanVal["PlanValidator"]:::control
    end

    %% Swimlane: Executor Hands (Data Plane)
    subgraph "Executor Hands"
        Exec["WorkflowExecutor"]:::control
        Manager["MCP Client Manager"]:::control
        subgraph "MCP Tool Services"
            FS["Filesystem"]:::data
            Mem["Memory"]:::data
            Term["Terminal"]:::data
        end
    end

    %% Swimlane: Data Stores
    subgraph "Data Stores"
        QDB["Qdrant DB"]:::data
        WF["workflows/"]:::data
        Schema["tools_schema.json"]:::data
    end

    %% Swimlane: External Services
    subgraph "External Services"
        LLM["LLM Endpoint"]:::external
    end

    %% Connections - User & CLI to Agent Brain
    CLI -->|"invokes"| Run
    Run -->|"starts planning"| Planner
    CLI -->|"ingest data"| Upsert

    %% RAG Retrieval
    Planner -->|"Tool RAG"| TR
    Planner -->|"Workflow RAG"| WR
    TR -->|"query mcp_tools"| QDB
    WR -->|"query mcp_workflows"| QDB
    TR --> PB
    WR --> PB

    %% Prompting & Validation
    PB -->|"build prompt"| LLC
    LLC -->|"LLM request"| LLM
    LLM -->|"PlanYAML"| LLC
    LLC --> PlanVal
    PlanVal -->|"valid plan"| Exec
    PlanVal -->|"invalid plan"| Planner

    %% Execution Flow
    Exec -->|"generate DAG"| Manager
    Manager --> FS
    Manager --> Mem
    Manager --> Term
    FS -->|"result"| Manager
    Mem -->|"result"| Manager
    Term -->|"result"| Manager
    Manager -->|"aggregate results"| Exec
    Exec -->|"results/logs"| CLI
    Exec --> WF
    Exec --> Schema
    Upsert -->|"ingest"| QDB

    %% Click Events
    click Run "https://github.com/veristamp/agentgovernor/blob/main/run.py"
    click Planner "https://github.com/veristamp/agentgovernor/blob/main/run_planner.py"
    click TR "https://github.com/veristamp/agentgovernor/blob/main/Agent/tool_retriever.py"
    click WR "https://github.com/veristamp/agentgovernor/blob/main/Agent/workflow_retriever.py"
    click PB "https://github.com/veristamp/agentgovernor/blob/main/Agent/prompt_builder.py"
    click LLC "https://github.com/veristamp/agentgovernor/blob/main/Agent/llm_client.py"
    click PlanVal "https://github.com/veristamp/agentgovernor/blob/main/Agent/plan_validator.py"
    click Exec "https://github.com/veristamp/agentgovernor/blob/main/mcp_client/workflow_executor.py"
    click Manager "https://github.com/veristamp/agentgovernor/blob/main/mcp_client/manager.py"
    click FS "https://github.com/veristamp/agentgovernor/blob/main/filesystem.py"
    click Mem "https://github.com/veristamp/agentgovernor/blob/main/memory.py"
    click Term "https://github.com/veristamp/agentgovernor/blob/main/terminal.py"
    click WF "https://github.com/veristamp/agentgovernor/tree/main/workflows/"
    click Schema "https://github.com/veristamp/agentgovernor/blob/main/tools_schema.json"
    click Upsert "https://github.com/veristamp/agentgovernor/blob/main/upsert.py"

    %% Styles
    classDef control fill:#E3F2FD,stroke:#42A5F5,stroke-width:1px
    classDef data fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
    classDef external fill:#E8F5E9,stroke:#66BB6A,stroke-dasharray: 5 5,stroke-width:1px
```
