# pirate-e/ai-workflow-task-agent architecture

> Architecture diagram of the GitHub repository pirate-e/ai-workflow-task-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pirate-e/ai-workflow-task-agent
- Repository: https://github.com/pirate-e/ai-workflow-task-agent

## Overview

##### Project Type & Purpose
- Type: Modular, enterprise-grade desktop AI assistant (CLI/console UI)
- Purpose: Hybrid AI integration (local Ollama + OpenAI/NVIDIA), multi-agent orchestration (LangGraph), dynamic Model Context Protocol (MCP) plugin system, rich error tracing, and professional workflows.

##### File Structure
Top-level directories:
– src/            : Core application code
– tools/          : 17-tool ecosystem (3 fundamental + 14 MCP filesystem tools)
– mcp/            : MCP server integration and dynamic registration
– ui/diagnostics/ : Rich Traceback & console UI
– config/         : Settings & logging configuration
– RAG/            : Retrieval-augmented graph (Neo4j)
– tests/          : Unit, integration, event-listener, serialization tests
– Dockerfile & docker-compose.yml: Containerization

##### Main Components & Their Relationships
A. Presentation Layer (Console UI)
- print_banner.py, print_message_style.py
- rich_error_print.py, rich_traceback_manager.py (diagnostics)
↕ (user input / output)
B. Orchestration Layer
- src/main_orchestrator.py (entry point)
- ChatInitializer → configures logging, loads .mcp.json, starts MCP servers
C. Routing & Classification
- classify_agent.py (detects “/agent” vs “/shell” vs normal chat)
- router.py (directs message to correct processor)
D. Processing Nodes
1. LLM Agent
– chat_llm.py (OpenAI/NVIDIA adapter with circuit breaker)
2. Tool Selector
– tool_selector.py
– tool_assign.py & tool_response_manager.py
3. Agent Orchestrator (Multi-step workflows)
– src/agents/agentic_orchestrator/AgentGraphCore.py
– hierarchical_agent_prompts.py
E. Tools Layer
1. Fundamental Tools (in-process)
– GoogleSearch, RAGSearch, Translate, RunShellCommand
2. MCP Filesystem Tools (plugin via JSON-RPC)
– dynamic registration (load_config.py + dynamically_tool_register.py)
– MCP manager subprocesses (manager.py)
F. Data & External Services
- Local Ollama host (HTTP on 11434)
- OpenAI/NVIDIA REST endpoints
- Neo4j graph database (for RAG)
- .mcp.json-driven Node.js MCP servers
G. Cross-Cutting Concerns
– config/settings.py (.env, MCP_CONFIG_PATH)
– configure_logging.py (structured, socket-based)
– event_listener.py & rich_status_listen.py (event bus, Rich.status)
– socket_manager.py (subprocess log routing)

##### Architectural Patterns & Design Principles
- Modular Monolith with clear separation of concerns
- Event-Driven (singleton EventManager, weak references)
- Strategy Pattern (ToolSelector + dynamic MCP mapping)
- Circuit Breaker Pattern (OpenAI/NVIDIA adapter)
- Plugin Architecture (MCP JSON-RPC, dynamic tool discovery)
- Singleton (StateAccessor in models/state.py)

##### Detailed Elements
– main_orchestrator.py (entry point)
– ChatInitializer (starts MCP, logging)
– Classifier & Router
– LLM Agent node & Circuit Breaker adapter
– Agentic orchestrator graph (planner → classifier → parameter generator → executor → synthesizer → validator → planner/finalizer)
– UI & Diagnostics (Rich Traceback, status listener)
– Config (.env, settings), Logging, Event Bus

– Comprehensive: showing all major modules and their interactions
– Accurate: aligned with the code structure and README architecture sections
– Actionable: illustrates dynamic plugin registration, multi-agent workflows, and fail-safe patterns

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        PrintBanner["print_banner.py"]:::frontend
        PrintMsgStyle["print_message_style.py"]:::frontend
        RichErrorPrint["rich_error_print.py"]:::frontend
        RichTracebackManager["rich_traceback_manager.py"]:::frontend
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        MainOrchestrator["main_orchestrator.py"]:::backend
        ChatInitializer["ChatInitializer"]:::backend
    end

    %% Routing & Classification
    subgraph "Routing & Classification"
        direction TB
        Classifier["classify_agent.py"]:::backend
        Router["router.py"]:::backend
    end

    %% Processing Nodes
    subgraph "Processing Nodes"
        direction TB
        LLMAgent["chat_llm.py\n(Circuit Breaker)"]:::backend
        ToolSelector["tool_selector.py"]:::backend
        ToolAssign["tool_assign.py"]:::backend
        ToolResponseMgr["tool_response_manager.py"]:::backend
        subgraph "Agent Orchestrator"
            direction TB
            AgentGraphCore["AgentGraphCore.py"]:::agent
            HierPrompts["hierarchical_agent_prompts.py"]:::agent
        end
    end

    %% Tools Layer
    subgraph "Tools Layer"
        direction TB
        subgraph "Fundamental Tools"
            direction TB
            GoogleSearch["GoogleSearch"]:::tools
            RAGSearch["RAGSearch"]:::tools
            Translate["Translate"]:::tools
            RunShellCmd["RunShellCommand"]:::tools
        end
        subgraph "MCP Filesystem Tools"
            direction TB
            LoadConfig["load_config.py"]:::plugin
            DynRegister["dynamically_tool_register.py"]:::plugin
            MCPManager["manager.py"]:::plugin
            MCPStruct["mcp_register_structure.py"]:::plugin
        end
    end

    %% External Services & Data Stores
    subgraph "External Services & Data Stores"
        direction TB
        Ollama["Local Ollama"]:::external
        OpenAI["OpenAI / NVIDIA"]:::external
        Neo4j["Neo4j Graph DB"]:::external
        MCPServer["Node.js MCP Servers"]:::external
    end

    %% Cross-Cutting Concerns
    subgraph "Cross-Cutting Concerns"
        direction TB
        Settings["settings.py"]:::crosscut
        ConfigureLogging["configure_logging.py"]:::crosscut
        EventListener["event_listener.py"]:::crosscut
        RichStatus["rich_status_listen.py"]:::crosscut
        SocketManager["socket_manager.py"]:::crosscut
        StateAccessor["state.py"]:::crosscut
    end

    %% Flows
    PrintBanner -->|"display/input"| MainOrchestrator
    PrintMsgStyle --> MainOrchestrator
    RichErrorPrint --> MainOrchestrator
    RichTracebackManager --> MainOrchestrator

    MainOrchestrator -->|init| ChatInitializer
    MainOrchestrator -->|call| ConfigureLogging
    MainOrchestrator -->|load settings| Settings
    ChatInitializer -->|register MCP| LoadConfig
    ChatInitializer -->|register MCP| DynRegister
    ChatInitializer -->|start MCP manager| MCPManager

    MainOrchestrator -->|route input| Classifier
    Classifier -->|classifies| Router
    Router -->|to LLM| LLMAgent
    Router -->|to Tools| ToolSelector
    Router -->|to Agent| AgentGraphCore

    LLMAgent -->|HTTP| OpenAI
    LLMAgent -->|HTTP| Ollama

    ToolSelector -->|select| ToolAssign
    ToolAssign -->|manage| ToolResponseMgr
    ToolResponseMgr -->|execute| GoogleSearch
    ToolResponseMgr -->|execute| RAGSearch
    ToolResponseMgr -->|execute| Translate
    ToolResponseMgr -->|execute| RunShellCmd
    ToolSelector -->|JSON-RPC| MCPManager
    MCPManager -->|spawn| MCPServer

    AgentGraphCore --> HierPrompts
    HierPrompts --> AgentGraphCore

    %% Return to UI
    LLMAgent -->|response| PrintBanner
    ToolResponseMgr -->|response| PrintBanner
    AgentGraphCore -->|response| PrintBanner

    %% Cross-cut links
    MainOrchestrator -.-> EventListener
    MainOrchestrator -.-> RichStatus
    MainOrchestrator -.-> SocketManager
    AgentGraphCore -.-> StateAccessor

    %% Click Events
    click PrintBanner "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/ui/print_banner.py"
    click PrintMsgStyle "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/ui/print_message_style.py"
    click RichErrorPrint "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/ui/rich_error_print.py"
    click RichTracebackManager "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/ui/diagnostics/rich_traceback_manager.py"
    click MainOrchestrator "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/main_orchestrator.py"
    click ChatInitializer "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/core/chat_initializer.py"
    click ConfigureLogging "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/config/configure_logging.py"
    click Settings "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/config/settings.py"
    click Classifier "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/agents/classify_agent.py"
    click Router "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/agents/router.py"
    click LLMAgent "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/agents/chat_llm.py"
    click ToolSelector "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/agents/tool_selector.py"
    click ToolAssign "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/tools/lggraph_tools/tool_assign.py"
    click ToolResponseMgr "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/tools/lggraph_tools/tool_response_manager.py"
    click AgentGraphCore "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/agents/agentic_orchestrator/AgentGraphCore.py"
    click HierPrompts "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/agents/agentic_orchestrator/hierarchical_agent_prompts.py"
    click GoogleSearch "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/tools/lggraph_tools/tools/google_search_tool.py"
    click RAGSearch "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/tools/lggraph_tools/tools/rag_search_classifier_tool.py"
    click Translate "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/tools/lggraph_tools/tools/translate_tool.py"
    click RunShellCmd "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/tools/lggraph_tools/tools/run_shell_command_tool.py"
    click LoadConfig "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/mcp/load_config.py"
    click DynRegister "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/mcp/dynamically_tool_register.py"
    click MCPManager "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/mcp/manager.py"
    click MCPStruct "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/mcp/mcp_register_structure.py"
    click EventListener "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/utils/listeners/event_listener.py"
    click RichStatus "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/utils/listeners/rich_status_listen.py"
    click SocketManager "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/utils/socket_manager.py"
    click StateAccessor "https://github.com/pirate-e/ai-workflow-task-agent/blob/main/src/models/state.py"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#2196F3,color:#0D47A1;
    classDef backend fill:#E8EAF6,stroke:#3F51B5,color:#1A237E;
    classDef agent fill:#FCE4EC,stroke:#E91E63,color:#880E4F;
    classDef tools fill:#E0F2F1,stroke:#009688,color:#004D40;
    classDef plugin fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef external fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20;
    classDef crosscut fill:#ECEFF1,stroke:#607D8B,color:#263238;
```
