# nwiizo/tfmcp architecture

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

- Interactive diagram: https://gitdiagram.com/nwiizo/tfmcp
- Repository: https://github.com/nwiizo/tfmcp

## Overview

##### Main Components
- CLI & Entry Point: Represented by the src/main.rs, this is the application’s starting point and command processor.
- MCP Server Component: Found within the src/mcp directory (including mcp/handler.rs and mcp/stdio.rs), this module handles the Model Context Protocol functionality to communicate with AI assistants.
- Terraform Integration Module: Located in src/terraform (with modules like service.rs, model.rs, and mod.rs) it captures Terraform configuration analysis, command execution, and state management.
- Core Business Logic: The src/core directory (with tfmcp.rs and core/mod.rs) encapsulates core operations, processing, and integration flows between the various modules.
- Configuration Handling & Shared Utilities: The src/config directory and src/shared (with logging and utilities) offer configuration management, logging support, and helper functions.
- Example & Rules: The example directory provides sample Terraform projects and environment configuration for testing/learning usage. The “rules” and “.cursor/rules” directories imply codified guidelines for standardized coding (for Rust, Terraform, mcp protocols), helping enforce best practices rather than affecting runtime behavior directly.
- Supporting Infrastructure: GitHub workflows, build scripts (build.rs, Release.sh) and .terraform-version files indicate automated build, deployment, and environmental consistency.

##### Relationships and Interactions
- User Interaction starts at the CLI entry (src/main.rs) which interprets commands (like “analyze” or “mcp”) and then routes execution either to the core logic or the MCP server.
- Core module functions act as mediators passing requests between the CLI, MCP, and Terraform modules.

##### Architectural Patterns and Design Principles
- Modularity: The codebase is clearly split into multiple submodules (CLI, MCP server, Terraform integration, etc.), which shows a clean separation of concerns.
- Extensibility: The use of “rules” directories suggests that the system follows guidelines for scalability and consistent coding patterns.
- Integration with External Tools: Emphasize how the system integrates with both the Terraform CLI (for infrastructure control) and with AI assistants (using the MCP protocol for remote management).

##### Including Technologies and Frameworks
- Rust is the primary programming language and platform (indicated by Cargo.toml and rust-toolchain.toml).
- Terraform CLI: This external dependency handles infrastructure as code, further integrated through the tfmcp tool.
- MCP (Model Context Protocol): The protocol mechanism that allows integration with AI platforms.
- Claude Desktop integration: This external tool is used for orchestrating Terraform operations via the MCP server.

##### Specific Elements to be Included
- From the CLI to Core Logic.
- From Core Logic to both the MCP Server and Terraform Integration modules.
- Supporting/utilities components (a third style).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Components
    A["CLI/Entry Point"]:::core
    B["Core Business Logic"]:::core
    C["MCP Server"]:::core
    D["Terraform Integration"]:::core
    E["External AI Assistant"]:::external
    F["External Terraform CLI/Environment"]:::external

    %% Supporting Modules and Other Components
    subgraph "Supporting Modules"
        G["Configuration Handling"]:::support
        H["Shared Utilities"]:::support
    end

    I["Example Projects"]:::support
    J["Code Guidelines/Rules"]:::support
    K["Supporting Infrastructure"]:::support

    %% Relationships
    A -->|"triggers"| B
    B -->|"activates"| C
    B -->|"activates"| D
    B -->|"initiates_sample_projects"| I
    C -->|"communicates_with"| E
    D -->|"invokes"| F

    %% Support arrows
    G -->|"supports"| B
    G -->|"supports"| C
    G -->|"supports"| D
    H -->|"supports"| A
    H -->|"supports"| B
    H -->|"supports"| D

    %% Additional guidelines and infrastructure
    J -.->|"guides_best_practices"| B
    K -.->|"ensures_build_consistency"| B

    %% Click Events
    click A "https://github.com/nwiizo/tfmcp/blob/main/src/main.rs"
    click B "https://github.com/nwiizo/tfmcp/blob/main/src/core/tfmcp.rs"
    click C "https://github.com/nwiizo/tfmcp/blob/main/src/mcp/handler.rs"
    click D "https://github.com/nwiizo/tfmcp/blob/main/src/terraform/service.rs"
    click G "https://github.com/nwiizo/tfmcp/blob/main/src/config/mod.rs"
    click H "https://github.com/nwiizo/tfmcp/blob/main/src/shared/logging.rs"
    click I "https://github.com/nwiizo/tfmcp/tree/main/example"
    click J "https://github.com/nwiizo/tfmcp/tree/main/.cursor/rules"
    click K "https://github.com/nwiizo/tfmcp/blob/main/.github/workflows/rust.yml"

    %% Styles
    classDef core fill:#F4AD42,stroke:#333,stroke-width:2px;
    classDef external fill:#9FDF9F,stroke:#333,stroke-width:2px;
    classDef support fill:#A2D2FF,stroke:#333,stroke-width:2px;
```
