---
name: tf-architecture-patterns
description: Terraform module design patterns, resource composition conventions, and project structure standards. Use when designing module structure, choosing resource composition patterns, or setting up project layout for AWS Terraform modules.
user-invocable: true
argument-hint: "No arguments — reference guide for module architecture patterns"
---

# Terraform Architecture Patterns

## Module-First Architecture

This repository develops well-structured, reusable Terraform modules using raw resources that follow HashiCorp and organizational best practices.

### Module Design Rules

- Author modules using native Terraform resources and data sources from official providers
- Follow the standard HashiCorp module structure: root module, `variables.tf`, `outputs.tf`, `examples/`, `tests/`
- Research AWS docs and provider docs before writing resource configurations
- Study well-regarded public registry modules for design patterns (e.g., `terraform-aws-modules/`)
- Expose configurable inputs with secure defaults
- Support conditional resource creation via `create_*` boolean variables
- Use semantic versioning (major.minor.patch) with clear CHANGELOG entries
- Use `>=` version constraints for providers in modules (maximize consumer compatibility)

## 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
├── 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.