# xmlking/agentic architecture

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

- Interactive diagram: https://gitdiagram.com/xmlking/agentic
- Repository: https://github.com/xmlking/agentic

## Overview

##### Main Components
- Agent Core Logic:
- The “src” directory contains the heart of the agent’s functionality. Key components include:
▪ src/agent – The central module for agent logic.
▪ src/evaluator – Likely used to process or validate outputs from the agents.
▪ src/loan, src/array, src/enum – Additional modules that may represent specific business logic or supporting functionalities.
- The “src/mcp” directory, divided into “sse” and “stdio,” indicates two separate communication channels or protocols (Server-Sent Events vs. Standard IO), representing flexible interaction modes between AI agents and external services.
- The “src/shared” value objects (models) indicate shared definitions used across components.

- Workflow Automation with n8n:
- The “config/n8n” folder includes credential configurations and multiple JSON workflows (e.g., 01_demo_workflow.json, 05_RAG_chatbot_for_movie_recommendations.json). This clearly signals that n8n is configured as an external automation and orchestration tool supporting agent interactions.

- Database and Other External Services:
- The configuration in “config/db” (including an initialization script) points to a database component.
- External integrations are evident through credential files for various services (GitHub, Azure Open AI, OpenAI, and others), thus showing external system integrations.

- Containerization and Deployment:
- Files such as “compose.yml” and “compose.orbstack.yml” as well as the Kubernetes configuration under “k8n/ai-gateway.yaml” demonstrate that deployment is managed via Docker Compose (or OrbStack) and potentially K8s for microservices/gateway routing.

- Documentation and Integration Examples:
- The “docs” folder, featuring markdown files like “ai-sdk.md” and “n8n.md”, supports understanding and integrating these components into product ideas like scheduling or secure document summarizing.

##### Relationships & Interactions
- The AI Agent (from the src/agent module) is the central piece; it interacts with:
- The evaluator module for processing LLM responses.
- The mcp modules for different communication protocols (SSE and stdio) which manage interactions with both internal and external consumers.
- n8n workflows (configured in the “config/n8n” folder) provide automation and integration with external APIs or systems based on data or events generated by the agent.
- The system communicates with a Database (initialized from “config/db”) which might serve as a storage layer for agent sessions, workflow states, or logging.
- Deployment artifacts (compose files and Kubernetes gateway) illustrate how the application is containerized and exposed.

##### Architectural Patterns & Principles
- Modular Design: The separation into “agent,” “evaluator,” “mcp,” etc. reflects a modular architecture, enabling experimentation with different interaction patterns.
- Communication Abstraction: Distinct directories for SSE and stdio within the MCP layer show that the system is built to handle different transport mechanisms.
- Workflow Integration: The n8n configuration emphasizes an event-driven and automation-centered design.
- Containerization & Orchestration: With dedicated docker-compose and Kubernetes config, the architecture embraces microservices principles and container orchestration for scalable deployment.

##### Overall Approach
- Then, subdivide each layer to map out the relevant modules and refine the interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core AI & Business Logic
    subgraph "Core AI & Business Logic"
        AgentModule["src/agent – Core agent logic"]:::core
        EvaluatorModule["src/evaluator – Evaluator logic"]:::core
        LoanModule["src/loan – Loan business logic"]:::core
        ArrayModule["src/array – Array business logic"]:::core
        EnumModule["src/enum – Enum business logic"]:::core
        SharedModels["src/shared/models.ts – Shared Models"]:::core
    end

    %% Communication Layer
    subgraph "Communication Layer"
        MCPSSE["src/mcp/sse – SSE Communication"]:::comm
        MCPStdio["src/mcp/stdio – Standard IO Communication"]:::comm
    end

    %% Workflow Automation
    subgraph "Workflow Automation"
        n8n["config/n8n – Workflow Automation & Credentials"]:::workflow
    end

    %% Data Storage
    subgraph "Data Storage"
        Database["config/db – Database Initialization & Config"]:::database
    end

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        DockerCompose["compose.yml – Docker Compose"]:::deployment
        OrbStack["compose.orbstack.yml – OrbStack Compose"]:::deployment
        KubernetesGateway["k8n/ai-gateway.yaml – Kubernetes API Gateway"]:::deployment
    end

    %% Documentation & Integration Examples
    subgraph "Documentation"
        Docs["docs – Documentation & Integration Examples"]:::docs
    end

    %% External Integrations
    subgraph "External Integrations"
        ExternalServices["External Service Integrations (GitHub,AzureOpenAI,OpenAI,etc.)"]:::external
    end

    %% Relationships within Core Components
    AgentModule -->|"calls"| EvaluatorModule
    AgentModule -->|"uses"| LoanModule
    AgentModule -->|"uses"| ArrayModule
    AgentModule -->|"uses"| EnumModule

    EvaluatorModule ---|"utilizes"| SharedModels
    LoanModule ---|"utilizes"| SharedModels
    ArrayModule ---|"utilizes"| SharedModels
    EnumModule ---|"utilizes"| SharedModels

    %% Relationships between Core and Communication
    AgentModule -->|"sendsData"| MCPSSE
    AgentModule -->|"sendsData"| MCPStdio

    %% Workflow Automation interactions
    n8n -->|"triggers"| AgentModule
    n8n -->|"logsTo"| Database

    %% Data Storage interaction
    AgentModule -->|"stores"| Database

    %% Deployment interactions
    DockerCompose -->|"deploys"| AgentModule
    DockerCompose -->|"deploys"| MCPSSE
    DockerCompose -->|"deploys"| MCPStdio

    OrbStack -->|"deploys"| AgentModule
    OrbStack -->|"deploys"| MCPSSE
    OrbStack -->|"deploys"| MCPStdio

    KubernetesGateway -->|"routesTo"| AgentModule
    KubernetesGateway -->|"routesTo"| MCPSSE
    KubernetesGateway -->|"routesTo"| MCPStdio

    %% External Integrations interaction
    ExternalServices -->|"providesCreds"| n8n

    %% Click Events
    click AgentModule "https://github.com/xmlking/agentic/tree/main/src/agent"
    click EvaluatorModule "https://github.com/xmlking/agentic/tree/main/src/evaluator"
    click LoanModule "https://github.com/xmlking/agentic/tree/main/src/loan"
    click ArrayModule "https://github.com/xmlking/agentic/tree/main/src/array"
    click EnumModule "https://github.com/xmlking/agentic/tree/main/src/enum"
    click MCPSSE "https://github.com/xmlking/agentic/tree/main/src/mcp/sse"
    click MCPStdio "https://github.com/xmlking/agentic/tree/main/src/mcp/stdio"
    click SharedModels "https://github.com/xmlking/agentic/blob/main/src/shared/models.ts"
    click n8n "https://github.com/xmlking/agentic/tree/main/config/n8n"
    click Database "https://github.com/xmlking/agentic/tree/main/config/db"
    click DockerCompose "https://github.com/xmlking/agentic/blob/main/compose.yml"
    click OrbStack "https://github.com/xmlking/agentic/blob/main/compose.orbstack.yml"
    click KubernetesGateway "https://github.com/xmlking/agentic/blob/main/k8n/ai-gateway.yaml"
    click Docs "https://github.com/xmlking/agentic/tree/main/docs"

    %% Class Definitions
    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef comm fill:#bbf,stroke:#333,stroke-width:2px;
    classDef workflow fill:#cfc,stroke:#333,stroke-width:2px;
    classDef database fill:#fc9,stroke:#333,stroke-width:2px;
    classDef deployment fill:#cff,stroke:#333,stroke-width:2px;
    classDef docs fill:#ffc,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;
```
