ThothCTL Framework Architecture¶

Note: This document provides a high-level overview of the framework architecture. For technical implementation details, see Software Architecture.

Overview¶

ThothCTL is an Internal Developer Platform (IDP) framework built on a 4-layer architecture that enables teams to build, manage, and operate infrastructure as code with built-in best practices, security, and AI assistance.

%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#3b82f6',
  'primaryTextColor':'#ffffff',
  'primaryBorderColor':'#2563eb',
  'lineColor':'#94a3b8',
  'secondaryColor':'#10b981',
  'tertiaryColor':'#8b5cf6',
  'background':'transparent',
  'mainBkg':'#3b82f6',
  'secondBkg':'#10b981',
  'tertiaryBkg':'#8b5cf6',
  'clusterBkg':'rgba(241, 245, 249, 0.05)',
  'clusterBorder':'#475569',
  'titleColor':'currentColor',
  'edgeLabelBackground':'transparent',
  'nodeTextColor':'#ffffff',
  'textColor':'currentColor',
  'nodeBorder':'#1e293b',
  'fontSize':'14px'
}}}%%
graph TB
    subgraph layer4["<b>🎨 Developer Experience Layer</b><br/><i>Intuitive interfaces and AI assistance</i>"]
        direction LR
        CLI["<b>CLI Interface</b><br/>Rich terminal UI<br/>Autocompletion<br/>Cross-platform"]
        AI["<b>AI Assistant</b><br/>Kiro CLI + MCP<br/>Natural language<br/>19 AI tools"]
        DOCS["<b>Documentation</b><br/>Auto-generation<br/>AI-powered<br/>Multi-format"]
        TMPL["<b>Templates</b><br/>Jinja2 engine<br/>Code generation<br/>Scaffolding"]
    end

    subgraph layer3["<b>⚡ Platform Capabilities Layer</b><br/><i>Core IDP functionality</i>"]
        direction LR
        SEC["<b>Security</b><br/>Checkov • Trivy<br/>KICS • OPA<br/>Compliance"]
        COST["<b>Cost Analysis</b><br/>Real-time pricing<br/>14 AWS services<br/>Optimization"]
        INV["<b>Inventory</b><br/>Dependencies<br/>Version tracking<br/>Reports"]
        VAL["<b>Validation</b><br/>Environment<br/>IaC checks<br/>Blast radius"]
        GEN["<b>Generation</b><br/>Stacks<br/>Components<br/>Boilerplate"]
    end

    subgraph layer2["<b>🔧 IaC Tool Integration Layer</b><br/><i>Multi-tool support through parsers and CLI</i>"]
        direction LR
        TF["<b>Terraform</b><br/>HCL Parser<br/>CLI Execution"]
        TG["<b>Terragrunt</b><br/>Parser Class<br/>CLI Execution"]
        TOFU["<b>OpenTofu</b><br/>HCL Parser<br/>CLI Execution"]
        CFN["<b>CloudFormation</b><br/>JSON/YAML<br/>AWS API"]
        CDK["<b>CDK v2</b><br/>Synth Parser<br/>CLI Execution"]
    end

    subgraph layer1["<b>🏗️ Foundation Layer</b><br/><i>Building blocks for the framework</i>"]
        direction LR
        SCAFFOLD["<b>Git Scaffolds</b><br/>Templates<br/>Best practices<br/>Reusable"]
        SPACE["<b>Spaces</b><br/>Multi-tenancy<br/>Credentials<br/>Isolation"]
        ENV["<b>Environment</b><br/>Tool bootstrap<br/>Cross-platform<br/>Automated"]
        CONFIG["<b>Configuration</b><br/>Hierarchical<br/>TOML format<br/>Overrides"]
    end

    CLI -.->|uses| SEC
    AI -.->|orchestrates| GEN
    DOCS -.->|leverages| TMPL

    SEC -.->|scans| TF
    COST -.->|analyzes| TG
    INV -.->|tracks| TOFU
    VAL -.->|validates| CFN
    GEN -.->|generates| CDK

    TF -.->|uses| SCAFFOLD
    TG -.->|operates in| SPACE
    TOFU -.->|requires| ENV
    CFN -.->|reads| CONFIG
    CDK -.->|uses| SCAFFOLD

    classDef layer4Style fill:#3b82f6,stroke:#60a5fa,stroke-width:3px,color:#fff
    classDef layer3Style fill:#10b981,stroke:#34d399,stroke-width:3px,color:#fff
    classDef layer2Style fill:#8b5cf6,stroke:#a78bfa,stroke-width:3px,color:#fff
    classDef layer1Style fill:#f59e0b,stroke:#fbbf24,stroke-width:3px,color:#fff

    class CLI,AI,DOCS,TMPL layer4Style
    class SEC,COST,INV,VAL,GEN layer3Style
    class TF,TG,TOFU,CFN,CDK layer2Style
    class SCAFFOLD,SPACE,ENV,CONFIG layer1Style

Framework Principles¶

ThothCTL aligns with IDP business objectives through five core principles:

Architecture Layers¶

Layer 1: Foundation Layer 🏗️¶

Building blocks for the framework

Official Scaffolds: - terraform-scaffold - Standard Terraform projects - terragrunt-scaffold - Multi-environment Terragrunt - terraform-module-scaffold - Reusable modules

Commands: thothctl init env, thothctl init space, thothctl init project

Layer 2: IaC Tool Integration Layer 🔧¶

Multi-tool support through parsers and CLI wrappers

Key Features: - Unified interface across tools - Tool-agnostic workflows - Version management - Execution orchestration

Commands: thothctl project iac, thothctl generate

Layer 3: Platform Capabilities Layer ⚡¶

Core IDP functionality

Security & Compliance¶

Multi-tool security scanning with Checkov, Trivy, KICS, and Snyk.

📖 Details: Security Scanning

Cost Analysis¶

Real-time AWS cost estimation with 14 services, automated HTML/JSON reports.

Commands: thothctl check iac -type cost-analysis

📖 Details: Cost Analysis

Inventory Management¶

Dependency tracking, version checking, professional HTML reports.

Commands: thothctl inventory iac --check-versions

📖 Details: Inventory Management

Validation¶

Environment validation, IaC checks, blast radius analysis.

Commands: thothctl check environment, thothctl check iac -type blast-radius

📖 Details: Validation

Code Generation¶

Stack generation, component creation, boilerplate automation.

Commands: thothctl generate

📖 Details: Code Generation

Layer 4: Developer Experience Layer 🎨¶

Intuitive interfaces and AI assistance

CLI Interface¶

Rich terminal UI with autocompletion, cross-platform support, and modern UX.

Features: - Click-based command structure - Rich console output - Shell autocompletion (bash, zsh, fish) - Progress indicators and spinners

AI Assistant (Kiro CLI)¶

Amazon Q integration with 19 specialized tools via Model Context Protocol (MCP).

Capabilities: - Natural language infrastructure queries - Code generation and modification - Documentation generation - Cost analysis assistance

📖 Details: AI-Powered Development

Documentation Generation¶

Automated documentation with AI-powered content generation.

Commands: thothctl document iac, thothctl document iac --ai

📖 Details: Documentation

Template Engine¶

Jinja2-based code generation with scaffolding support.

Features: - Variable substitution - Conditional logic - Loops and filters - Custom functions

📖 Details: Template Engine

Use Cases¶

ThothCTL supports comprehensive IDP workflows:

📖 Complete Use Cases: Use Cases Documentation

Integration Points¶

Version Control Systems¶

• GitHub (OAuth, Personal Access Tokens)
• GitLab (OAuth, Personal Access Tokens)
• Azure DevOps (Personal Access Tokens)

Cloud Providers¶

• AWS (IAM credentials, SSO)
• Azure (Service Principal)
• GCP (Service Account)

CI/CD Platforms¶

• GitHub Actions
• GitLab CI
• Azure Pipelines
• Jenkins

AI Services¶

• Amazon Q (via Kiro CLI)
• Model Context Protocol (MCP)

Configuration Hierarchy¶

1. Global Config      (~/.thothctl/config.toml)
2. Space Config       (.thothcf-<space>.toml)
3. Project Config     (.thothcf.toml)
4. Environment Vars   (THOTHCTL_*)

Example Configuration:

[project]
name = "my-infrastructure"
type = "terraform"

[space]
name = "lab-github"
vcs = "github"

[tools]
terraform_version = "1.6.0"
terragrunt_version = "0.54.0"

Next Steps¶

• Getting Started: Quick Start Guide
• Commands Reference: Commands Documentation
• Use Cases: Use Cases & Examples
• Technical Details: Software Architecture
• Template Engine: Template System