Tf Architecture Patterns

Module Usage Pattern (in examples/)

# examples/basic/main.tf
module "this" {
  source = "../.."

  name        = "my-vpc"
  vpc_cidr    = "10.0.0.0/16"
  environment = "dev"

  tags = {
    Application = "example"
    ManagedBy   = "terraform"
  }
}

Project Structure Convention

/
├── main.tf              # Primary resource definitions
├── variables.tf         # Input variables with validation
├── outputs.tf           # Output values with descriptions
├── locals.tf            # Computed values
├── versions.tf          # Terraform and provider version constraints (required_version + required_providers)
├── README.md            # Auto-generated via terraform-docs
├── CHANGELOG.md         # Version history
├── examples/
│   ├── basic/           # Minimal usage example (with provider config)
│   └── complete/        # Full-featured example
├── modules/             # Submodules (optional)
├── tests/               # Terraform test files (.tftest.hcl)
└── .github/
    └── workflows/       # CI/CD pipelines

File Organization Rules

• No monolithic files exceeding 500 lines
• No intermingling resource types without logical grouping
• No default values for security-sensitive variables
• No provider configuration in the root module
• Variables: snake_case with descriptive names
• Resources: Use this for single primary resource, descriptive names for multiples
• Prefer for_each over count for resource iteration (stable addresses)

Security-First Defaults

Security defaults per constitution sections 1.2 and 4.x. Key: zero trust, encryption by default, least privilege, sensitive = true on secrets.

AWS Architecture Patterns

For resource-level implementation patterns (VPC, IAM, compute, storage, database), see tf-implementation-patterns skill.

AWS Style Requirements

Mandatory Resource Tagging (AWS-TAG-001 - MUST)

All taggable AWS resources MUST support tags via a tags variable. Use merge() to combine consumer tags with module defaults:

resource "aws_vpc" "this" {
  # ...
  tags = merge(var.tags, { Name = var.name })
}

Note: default_tags configuration belongs in examples/ provider blocks, not in the module root.

AWS Resource Naming (AWS-NAME-001 - SHOULD)

Use this for single primary resources. Use descriptive names for multiples:

resource "aws_vpc" "this" { ... }
resource "aws_subnet" "public" { ... }
resource "aws_subnet" "private" { ... }

AWS Provider Configuration (AWS-PROV-001 - SHOULD)

• Use >= version constraints for providers in modules
• Multi-region: use clear provider aliases in examples
• Root module MUST NOT contain provider configuration blocks