# vision-of-chosen/iac-drift-multi-agents architecture

> Architecture diagram of the GitHub repository vision-of-chosen/iac-drift-multi-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vision-of-chosen/iac-drift-multi-agents
- Repository: https://github.com/vision-of-chosen/iac-drift-multi-agents

## Overview

##### Project type and purpose
- This is an open-source, terminal-based, multi-agent orchestration system written in Python.
- Its job is to detect Terraform infrastructure drift, analyze its severity, then automatically generate and apply remediation plans.
- It uses the strand-agents SDK and AWS services (Terraform CLI, AWS APIs, Anthropic Claude via AWS Bedrock).

##### File structure
- Top-level scripts and configuration
- terraform_drift_system.py – main entry point
- chat_interface.py – terminal chat UI
- config.py / prompts.py – global settings, system prompts
- shared_memory.py – blackboard/shared memory implementation
- requirements.txt, .env.example, setup.sh
- Agents directory
- orchestration_agent.py – central coordinator
- detect_agent.py – drift detection specialist
- drift_analyzer_agent.py – analysis & assessment
- remediate_agent.py – automated remediation
- Third-party SDKs and tools
- sdk-python/ – local install of strand-agents SDK
- tools/ – custom toolset wrappers (strand-tools, use_aws, file writers)
- Terraform workspace
- terraform/ – user’s .tf, .tfstate, variables, outputs
- terraform/*.tf scripts invoked by agents
- Infrastructure-as-code orchestration
- terraform_drift_system.py + terraform_drift_system.py calls into terraform/ directory

##### README insights
- Four specialized agents collaborate via a shared-memory (blackboard) pattern.
- Workflow:
User → Chat UI → OrchestrationAgent → {DetectAgent → SharedMemory → DriftAnalyzerAgent → SharedMemory → RemediateAgent} → OrchestrationAgent → User
- Integrations: Terraform CLI, AWS CLI/SDKs, Anthrop­ic Claude (via AWS Bedrock), strand-tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI & Orchestration Layer
    subgraph "UI & Orchestration"
        direction TB
        ChatUI["Chat Interface (Terminal UI)"]:::ui
        Main["Main Entry Point: terraform_drift_system.py"]:::orchestration
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        ConfigSettings["Global Settings: config.py"]:::config
        ConfigPrompts["System Prompts: prompts.py"]:::config
    end

    %% Agents Layer
    subgraph "Agents (Chain-of-Responsibility)" 
        direction TB
        OrchestrationAgent["OrchestrationAgent"]:::agent
        DetectAgent["DetectAgent"]:::agent
        DriftAnalyzerAgent["DriftAnalyzerAgent"]:::agent
        RemediateAgent["RemediateAgent"]:::agent
    end

    %% Shared Memory
    SharedMemory[("Shared Memory\n(Blackboard)")]:::shared

    %% Tools & SDK Layer
    subgraph "Tools & SDK"
        direction TB
        SDK["Third-Party SDK\n(sdk-python/)"]:::tools
        ToolWrappers["Tool Wrappers & Utilities"]:::tools
    end

    %% Infrastructure Layer
    subgraph "Infrastructure-as-Code"
        direction TB
        TerraformDir["Terraform Workspace\n(terraform/)"]:::infra
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        AWSAPIs["AWS APIs"]:::external
        AWSBedrock["AWS Bedrock\n(Anthropic Claude)"]:::external
    end

    %% Environment & Setup
    subgraph "Environment & Setup"
        direction TB
        Env[".env.example"]:::devops
        Requirements["requirements.txt"]:::devops
        Setup["setup.sh"]:::devops
        Demo["demo_drift_creation.py"]:::devops
        README1["README.md"]:::docs
        README2["drift_system_README.md"]:::docs
    end

    %% Connections
    User["User"]:::user -->|user_request| ChatUI
    ChatUI -->|start_process| Main
    Main -->|load_config| ConfigSettings
    Main -->|load_prompts| ConfigPrompts
    Main -->|invoke| OrchestrationAgent

    OrchestrationAgent -->|enqueue_tasks| DetectAgent
    OrchestrationAgent -->|enqueue_tasks| DriftAnalyzerAgent
    OrchestrationAgent -->|enqueue_tasks| RemediateAgent

    DetectAgent -->|write_drift_report| SharedMemory
    DetectAgent -->|query_state| AWSAPIs
    DetectAgent -->|use_wrapper| ToolWrappers

    DriftAnalyzerAgent -->|read_drift_report| SharedMemory
    DriftAnalyzerAgent -->|write_analysis| SharedMemory
    DriftAnalyzerAgent -->|llm_reasoning| AWSBedrock

    RemediateAgent -->|read_recommendations| SharedMemory
    RemediateAgent -->|generate_tf| ToolWrappers
    RemediateAgent -->|apply_plan| TerraformDir
    RemediateAgent -->|write_results| SharedMemory

    SharedMemory -->|status_updates| OrchestrationAgent
    OrchestrationAgent -->|send_updates| ChatUI

    Main -->|uses_sdk| SDK

    %% Click Events
    click ChatUI "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/chat_interface.py"
    click Main "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/terraform_drift_system.py"
    click ConfigSettings "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/config.py"
    click ConfigPrompts "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/prompts.py"
    click SharedMemory "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/shared_memory.py"
    click OrchestrationAgent "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/agents/orchestration_agent.py"
    click DetectAgent "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/agents/detect_agent.py"
    click DriftAnalyzerAgent "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/agents/drift_analyzer_agent.py"
    click RemediateAgent "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/agents/remediate_agent.py"
    click TerraformDir "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/terraform/main.tf"
    click SDK "https://github.com/vision-of-chosen/iac-drift-multi-agents/tree/main/sdk-python/"
    click ToolWrappers "https://github.com/vision-of-chosen/iac-drift-multi-agents/tree/main/tools/"
    click Env "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/.env.example"
    click Requirements "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/requirements.txt"
    click Setup "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/setup.sh"
    click Demo "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/demo_drift_creation.py"
    click README1 "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/README.md"
    click README2 "https://github.com/vision-of-chosen/iac-drift-multi-agents/blob/main/drift_system_README.md"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef orchestration fill:#B3D4FC,stroke:#005CBF,color:#005CBF;
    classDef config fill:#E8E8E8,stroke:#666666,color:#333333;
    classDef agent fill:#DFFDE0,stroke:#28A745,color:#155724;
    classDef shared fill:#FFF5B1,stroke:#FFC107,color:#856404;
    classDef tools fill:#FFF2CC,stroke:#FFC107,color:#8A6D3B;
    classDef infra fill:#FFE5CC,stroke:#FF8C00,color:#A55200;
    classDef external fill:#FFE5E5,stroke:#DC3545,color:#721C24;
    classDef devops fill:#F0F0F0,stroke:#777777,color:#333333;
    classDef docs fill:#F7F7F7,stroke:#999999,color:#555555;
    classDef user fill:none,stroke:none,color:#000000;
```
