Terry-Form MCP

--- title: Architecture Overview description: High-level architecture of Terry-Form MCP order: 1 --- # Architecture Overview Terry-Form MCP is designed with security, scalability, and extensibility at its core. This document provides a comprehensive overview of the system architecture. ## System Architecture ```mermaid graph TB subgraph "Client Layer" A[AI Assistant<br/>Claude/ChatGPT] B[Web Browser<br/>Dashboard] C[CLI Tools] D[CI/CD Systems] end subgraph "Terry-Form MCP Core" E[MCP Protocol Handler] F[Web API Server] G[Security Layer] H[Request Router] subgraph "Execution Engine" I[Terraform Executor] J[Command Validator] K[State Manager] end subgraph "Integration Layer" L[GitHub App Handler] M[Cloud Provider APIs] N[Terraform Cloud Client] end subgraph "Intelligence Layer" O[Module Analyzer] P[Security Scanner] Q[Best Practice Engine] end end subgraph "External Services" R[GitHub Repositories] S[Terraform Cloud] T[AWS/Azure/GCP] U[Container Registry] end A -->|MCP Protocol| E B -->|HTTP/WebSocket| F C -->|MCP Protocol| E D -->|API/MCP| E E --> G F --> G G --> H H --> I H --> L H --> O I --> J I --> K J --> I L --> R M --> T N --> S O --> P O --> Q style G fill:#ff9999 style J fill:#ff9999 ``` ## Core Components ### 1. Protocol Layer The protocol layer handles communication between clients and the Terry-Form server. ```mermaid sequenceDiagram participant Client as AI Assistant participant MCP as MCP Handler participant Security as Security Layer participant Executor as Terraform Executor Client->>MCP: Tool Request MCP->>Security: Validate Request Security->>Security: Check Permissions Security->>Security: Sanitize Input Security-->>MCP: Validated Request MCP->>Executor: Execute Command Executor->>Executor: Run Terraform Executor-->>MCP: Result MCP-->>Client: Response ``` ### 2. Security Architecture Security is implemented in multiple layers: ```mermaid graph LR subgraph "Security Layers" A[Input Validation] B[Path Traversal Protection] C[Command Injection Prevention] D[Action Whitelisting] E[Resource Isolation] F[Audit Logging] end A --> B B --> C C --> D D --> E E --> F ``` **Key Security Features:** - **Input Validation**: All inputs are validated against strict schemas - **Path Protection**: Prevents access outside designated workspace - **Command Safety**: Uses `shell=False` and `shlex.quote()` for subprocess execution - **Action Control**: Whitelist of allowed Terraform actions - **Isolation**: Docker containers with limited capabilities ### 3. Execution Engine The execution engine manages Terraform operations safely: ```mermaid stateDiagram-v2 [*] --> Idle Idle --> Validating: Receive Request Validating --> Preparing: Valid Request Validating --> Error: Invalid Request Preparing --> Executing: Setup Complete Executing --> Processing: Command Running Processing --> Success: Command Success Processing --> Failed: Command Failed Success --> Idle: Return Result Failed --> Idle: Return Error Error --> Idle: Return Error ``` ### 4. Data Flow ```mermaid graph TD subgraph "Request Flow" A[Client Request] --> B{Request Type} B -->|Terraform Op| C[Terraform Handler] B -->|GitHub Op| D[GitHub Handler] B -->|Cloud Op| E[Cloud Handler] C --> F[Validation] D --> F E --> F F --> G{Valid?} G -->|Yes| H[Execute] G -->|No| I[Reject] H --> J[Process Result] J --> K[Format Response] K --> L[Return to Client] I --> L end ``` ## Deployment Architecture ### Docker Deployment ```mermaid graph TB subgraph "Docker Container" A[Terry-Form MCP] B[Python Runtime] C[Terraform Binary] D[Security Tools] E[Git Client] end subgraph "Volume Mounts" F[/mnt/workspace] G[/app/config] H[/var/log] end subgraph "Network" I[Port 3000: MCP] J[Port 8001: Web] end A --> F A --> G A --> H A --> I A --> J ``` ### Kubernetes Architecture ```mermaid graph TB subgraph "Kubernetes Cluster" subgraph "Terry-Form Namespace" A[Deployment] B[Service] C[ConfigMap] D[Secret] E[PVC] F[HPA] G[NetworkPolicy] end subgraph "Ingress" H[Ingress Controller] I[TLS Termination] end subgraph "Monitoring" J[Prometheus] K[Grafana] L[Loki] end end H --> B A --> E A --> C A --> D F --> A G --> A A --> J A --> L ``` ## Integration Architecture ### GitHub App Integration ```mermaid sequenceDiagram participant User participant TerryForm as Terry-Form participant GitHub participant Workspace User->>TerryForm: Clone Repository TerryForm->>GitHub: Authenticate (JWT) GitHub-->>TerryForm: Installation Token TerryForm->>GitHub: Clone Repo GitHub-->>TerryForm: Repository Data TerryForm->>Workspace: Store Files TerryForm-->>User: Success ``` ### Multi-Cloud Support ```mermaid graph LR subgraph "Terry-Form MCP" A[Cloud Abstraction Layer] end subgraph "Cloud Providers" B[AWS Provider] C[Azure Provider] D[GCP Provider] E[Terraform Cloud] end A --> B A --> C A --> D A --> E B --> F[AWS APIs] C --> G[Azure APIs] D --> H[GCP APIs] E --> I[TFC APIs] ``` ## Scalability Considerations ### Horizontal Scaling ```mermaid graph TB subgraph "Load Balancer" A[HAProxy/Nginx] end subgraph "Terry-Form Instances" B[Instance 1] C[Instance 2] D[Instance 3] end subgraph "Shared Storage" E[State Storage] F[Workspace Storage] end subgraph "Cache Layer" G[Redis Cache] end A --> B A --> C A --> D B --> E B --> F B --> G C --> E C --> F C --> G D --> E D --> F D --> G ``` ### Performance Optimization - **Caching**: Module analysis results cached - **Connection Pooling**: Reuse cloud provider connections - **Async Operations**: Non-blocking I/O for better concurrency - **Resource Limits**: CPU/Memory limits per operation ## Security Architecture Details ### Defense in Depth ```mermaid graph TD subgraph "Layer 1: Network" A[TLS Encryption] B[Firewall Rules] C[DDoS Protection] end subgraph "Layer 2: Application" D[Authentication] E[Authorization] F[Input Validation] end subgraph "Layer 3: Execution" G[Sandboxing] H[Resource Limits] I[Audit Logging] end subgraph "Layer 4: Data" J[Encryption at Rest] K[Secret Management] L[Access Control] end A --> D B --> D C --> D D --> G E --> G F --> G G --> J H --> J I --> J ``` ## Monitoring and Observability ### Metrics Collection ```mermaid graph LR subgraph "Terry-Form MCP" A[Application Metrics] B[System Metrics] C[Custom Metrics] end subgraph "Collection" D[Prometheus Exporter] E[StatsD Client] end subgraph "Storage" F[Prometheus] G[InfluxDB] end subgraph "Visualization" H[Grafana] I[Custom Dashboards] end A --> D B --> D C --> E D --> F E --> G F --> H G --> H H --> I ``` ## High Availability Setup ```mermaid graph TB subgraph "Region 1" A1[Terry-Form Primary] B1[Database Primary] C1[Cache Primary] end subgraph "Region 2" A2[Terry-Form Secondary] B2[Database Replica] C2[Cache Replica] end subgraph "Global" D[Global Load Balancer] E[Shared Object Storage] end D --> A1 D --> A2 A1 --> B1 A1 --> C1 A1 --> E A2 --> B2 A2 --> C2 A2 --> E B1 -.->|Replication| B2 C1 -.->|Replication| C2 ``` ## Development Architecture ### Local Development Setup ```mermaid graph TD subgraph "Developer Machine" A[IDE/Editor] B[Terry-Form Dev Server] C[Local Terraform] D[Docker Desktop] end subgraph "Test Environment" E[Test Workspace] F[Mock Cloud APIs] G[Test State Storage] end A --> B B --> C B --> E E --> F E --> G D --> B ``` ## Next Steps - Return to [Architecture Index]({{ site.baseurl }}/architecture/) for overview - Explore [Security Guide]({{ site.baseurl }}/guides/security) for security best practices