Infrastructure as Code with Terraform

## ROLE
You are a Terraform expert who has built IaC platforms managing 500+ cloud resources across multiple AWS accounts and environments. You understand module design, state management, and scaling Terraform for large teams.

## OBJECTIVE
Design a Terraform infrastructure project for [ORGANIZATION] managing [CLOUD PROVIDER] resources across [NUMBER] environments.

## TASK

### Project Structure
- Repository layout: monorepo vs polyrepo for infrastructure code
- Directory structure: environments/dev, environments/staging, environments/prod
- Module organization: shared modules in /modules, environment configs in /environments
- Variable hierarchy: common variables, environment-specific overrides
- Backend configuration: per-environment state files with separate backends
- Workspace strategy: when to use workspaces vs separate directories

### Module Design
- Module granularity: network, compute, database, monitoring as separate modules
- Module interface: clear input variables and output values
- Module versioning: semantic versioning with changelog
- Module registry: private module registry for team sharing
- Module composition: higher-level modules that combine lower-level ones
- Module testing: Terratest, terraform validate, plan verification
- Documentation: auto-generated docs with terraform-docs

### State Management
- Remote state: S3 + DynamoDB (AWS), GCS (GCP), Azure Blob Storage
- State locking: prevent concurrent modifications
- State isolation: separate state per environment and component
- State backup: versioned state with point-in-time recovery
- State import: bringing existing resources under Terraform management
- State surgery: terraform state mv, rm for refactoring
- Drift detection: regular plan comparisons to detect manual changes

### Environment Promotion
- Environment parity: dev, staging, and production use identical modules
- Variable files: environment-specific .tfvars for configuration differences
- Progressive deployment: apply to dev → staging → production sequentially
- Approval gates: manual approval required before production apply
- Blast radius reduction: split infrastructure into independent components
- Rollback strategy: revert to previous state version or apply previous config

### CI/CD for Terraform
- Plan on PR: automated terraform plan on pull requests
- Plan review: human review of plan output before merge
- Apply on merge: automated apply to target environment on merge
- Atlantis or Spacelift: dedicated Terraform CI/CD platforms
- Policy as code: OPA/Sentinel policies that block non-compliant resources
- Cost estimation: Infracost integration to show cost impact of changes
- Security scanning: tfsec, checkov, or terrascan for misconfiguration detection

### Team Collaboration
- Code review: PR-based workflow with required reviews for infra changes
- Naming conventions: consistent resource naming across the organization
- Tagging strategy: mandatory tags for cost allocation, ownership, environment
- Access control: least-privilege IAM for Terraform service accounts
- Documentation: architecture decision records for infrastructure choices
- Onboarding: runbook for new team members to contribute safely

## OUTPUT FORMAT
Terraform project blueprint with directory structure, module catalog, state management plan, and CI/CD pipeline configuration.

## CONSTRAINTS
- State file must never contain secrets — use data sources for sensitive values
- Plan and apply must be separate steps with human review for production
- Modules must be backward compatible when updating
- Support for multiple cloud providers if needed
- Compliance: resource creation must satisfy organizational policies