# versuscontrol/ai-infrastructure-agent architecture

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

- Interactive diagram: https://gitdiagram.com/versuscontrol/ai-infrastructure-agent
- Repository: https://github.com/versuscontrol/ai-infrastructure-agent

## Overview

##### Project type and purpose
- From the README and file tree, this is a full-stack Proof-of-Concept “AI Infrastructure Agent” that exposes a Web UI (dashboard) and a backend MCP Server which orchestrates an AI-driven AWS infrastructure manager.
- Key purpose: translate natural-language requests into safe AWS operations via AI planning, conflict detection, state management, and a visual web dashboard.

##### File structure
Top-level directories:
- cmd/web – Go entrypoint for the Web UI server (serves static assets + templates)
- cmd/server – Go entrypoint for the MCP Server (agent core + protocol server)
- web/ – React-style static assets (JS/CSS) and HTML templates under web/static & web/templates
- pkg/ – Core libraries, broken out by domain:
– pkg/agent: AI planning, request processing, execution, dependency resolution
– pkg/mcp: MCP protocol implementation (server, resource registry)
– pkg/aws & pkg/adapters: AWS SDK clients + adapter layer for each AWS resource
– pkg/state: Terraform-like state management & conflict detection
– pkg/discovery, pkg/graph, pkg/conflict: resource scanning, graph analysis, conflict resolution
– pkg/tools: helper functions for AWS resources
– pkg/web: optional shared HTTP handlers (if used)
- internal/: config loading and logging primitives
- scripts/: install and launcher helpers

##### Key insights from the README
- Components: Dashboard (forms + monitoring), Agent Core, AI Provider, AWS Client, State Management
- Safety features: Dry-run, conflict detection, drift management

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Web UI Service"
        direction TB
        Browser["User Browser"]:::external
        subgraph "Web Interface Layer"
            direction TB
            UIEntrypoint["cmd/web/main.go"]:::presentation
            ServerHandler["pkg/web/server.go"]:::presentation
            StaticAssets["web/static/app.js\nweb/static/style.css"]:::presentation
            Templates["web/templates/dashboard.html"]:::presentation
        end
    end

    %% Backend Layer
    subgraph "MCP Server Service"
        direction TB
        MCPEnt["cmd/server/main.go"]:::backend
        subgraph "MCP Protocol Layer"
            direction TB
            MCPServer["pkg/mcp/server.go"]:::backend
            ToolManager["pkg/mcp/tool_manager.go"]:::backend
            ResourceRegistry["pkg/mcp/resource_registry.go"]:::backend
            ServerIntegration["pkg/mcp/server_integration.go"]:::backend
        end
        subgraph "Agent Core"
            direction TB
            ReqProcessor["pkg/agent/agent_request_processor.go"]:::backend
            PlanExecutor["pkg/agent/agent_plan_executor.go"]:::backend
            CapabilityExt["pkg/agent/agent_capability_extractors.go"]:::backend
            DepResolver["pkg/agent/agent_dependency_resolver.go"]:::backend
            MCPComm["pkg/agent/mcp_communication.go"]:::backend
        end
        subgraph "State & Conflict Management"
            direction TB
            StateMgr["pkg/state/manager.go"]:::backend
            ConflictRes["pkg/conflict/resolver.go"]:::backend
            Discovery["pkg/discovery/scanner.go"]:::backend
            GraphAnalyzer["pkg/graph/analyzer.go"]:::backend
            GraphManager["pkg/graph/manager.go"]:::backend
        end
        subgraph "AWS Adapters & SDK"
            direction TB
            AWSClient["pkg/aws/client.go\npkg/aws/ec2.go\npkg/aws/rds.go\npkg/aws/vpc.go\npkg/aws/alb.go\npkg/aws/asg.go\npkg/aws/security_group.go"]:::adapters
            Adapters["pkg/adapters/base.go\npkg/adapters/ec2.go\npkg/adapters/rds.go\npkg/adapters/vpc.go\npkg/adapters/alb.go\npkg/adapters/asg.go\npkg/adapters/security_group.go"]:::adapters
        end
        subgraph "Interfaces & Tools"
            direction TB
            Interfaces["pkg/interfaces/aws_resource.go\npkg/interfaces/mcp_tool.go\npkg/interfaces/state_management.go"]:::utility
            Tools["pkg/tools/ec2_tools.go\npkg/tools/vpc_tools.go\npkg/tools/state_tools.go"]:::utility
        end
        MCPEnt --> MCPServer
        MCPServer --> ToolManager
        MCPServer --> ResourceRegistry
        MCPServer --> ServerIntegration
        MCPEnt --> ReqProcessor
        ReqProcessor --> PlanExecutor
        PlanExecutor --> CapabilityExt
        CapabilityExt --> DepResolver
        DepResolver --> MCPComm
        MCPComm -->|calls| MCPServer
        ReqProcessor --> StateMgr
        StateMgr --> ConflictRes
        StateMgr --> Discovery
        StateMgr --> GraphAnalyzer
        GraphAnalyzer --> GraphManager
        ReqProcessor --> AWSClient
        AWSClient --> Adapters
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AIProvider["AI Providers (OpenAI, Gemini, Anthropic)"]:::external
        AWSCloud["AWS Cloud\n(EC2, RDS, VPC, ALB, ASG, SG)"]:::external
    end

    %% Utilities
    subgraph "Config & Logging"
        direction TB
        Config["internal/config/config.go\nconfig.openai.yaml.example"]:::utility
        Logging["internal/logging/logger.go"]:::utility
        Scripts["scripts/install.sh\nscripts/run-web-ui.sh"]:::utility
    end

    %% Flows
    Browser -->|"HTTP/WS"| StaticAssets
    Browser -->|"HTTP/WS"| Templates
    StaticAssets -->|served by| ServerHandler
    Templates -->|served by| ServerHandler
    ServerHandler -->|in-process| UIEntrypoint

    UIEntrypoint -->|HTTP/gRPC| MCPEnt
    MCPEnt --> ReqProcessor

    ReqProcessor -->|AI prompt → API| AIProvider
    AIProvider -->|response| ReqProcessor

    PlanExecutor -->|state ops| StateMgr
    StateMgr -->|detect conflicts| ConflictRes
    ConflictRes -->|feedback| PlanExecutor

    PlanExecutor -->|execute| Adapters
    Adapters -->|calls| AWSCloud
    AWSCloud -->|events/logs| MCPEnt
    MCPEnt -->|monitoring updates| ServerHandler

    Config --> MCPEnt
    Logging --> MCPEnt

    %% Click Events
    click UIEntrypoint "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/cmd/web/main.go"
    click ServerHandler "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/web/server.go"
    click StaticAssets "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/web/static/app.js"
    click StaticAssets "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/web/static/style.css"
    click Templates "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/web/templates/dashboard.html"
    click MCPEnt "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/cmd/server/main.go"
    click MCPServer "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/mcp/server.go"
    click ToolManager "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/mcp/tool_manager.go"
    click ResourceRegistry "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/mcp/resource_registry.go"
    click ServerIntegration "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/mcp/server_integration.go"
    click ReqProcessor "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/agent/agent_request_processor.go"
    click PlanExecutor "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/agent/agent_plan_executor.go"
    click CapabilityExt "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/agent/agent_capability_extractors.go"
    click DepResolver "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/agent/agent_dependency_resolver.go"
    click MCPComm "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/agent/mcp_communication.go"
    click Config "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/internal/config/config.go"
    click AWSClient "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/aws/client.go"
    click Adapters "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/adapters/base.go"
    click StateMgr "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/state/manager.go"
    click ConflictRes "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/conflict/resolver.go"
    click Discovery "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/discovery/scanner.go"
    click GraphAnalyzer "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/graph/analyzer.go"
    click GraphManager "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/graph/manager.go"
    click Interfaces "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/interfaces/aws_resource.go"
    click Tools "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/pkg/tools/ec2_tools.go"
    click Logging "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/internal/logging/logger.go"
    click Scripts "https://github.com/versuscontrol/ai-infrastructure-agent/blob/main/scripts/install.sh"

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E6FFE6,stroke:#28A745,color:#28A745
    classDef adapters fill:#FFF4E6,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#F0F0F0,stroke:#555555,color:#555555
    classDef utility fill:#F5F5F5,stroke:#999999,color:#999999
```
