Terraform layout

Shared AWS resources (API Gateway, WAF, DynamoDB, S3) provisioned in Terraform. Per-service resources (Lambda, methods, IAM) by Serverless.

Only run terraform plan + terraform init locally. apply/destroy go through CI/CD.

Layout

platform/terraform/
├── env-ci/         # CircleCI project + per-env contexts
├── env-dev/        # dev AWS resources (canonical source)
│   ├── main.tf               # provider, backend, locals (per-env)
│   ├── variables.tf          # per-env defaults (per-env)
│   ├── main.apig.tf          # API Gateway REST API + custom domain
│   
│   ├── main.cloudwatch.tf    # log groups, alarms
│   ├── main.cmstosocial.tf   # cmstosocial-specific resources
│   ├── main.dynamodb.tf      # DynamoDB tables
│   ├── main.waf.tf + main.waf.*.tf  # WAF ACL + rules + logging
├── env-staging/    # staging (symlinks resource files from env-dev)
│   ├── main.tf               # per-env
│   ├── variables.tf          # per-env
│   └── main.*.tf -> ../env-dev/main.*.tf
├── env-prod/       # prod (symlinks resource files from env-dev)
│   ├── main.tf               # per-env
│   ├── variables.tf          # per-env
│   └── main.*.tf -> ../env-dev/main.*.tf
├── env-docs/       # docs site (Cloudflare Pages) - separate stack
└── CLAUDE.md

Environments

Env	TFC workspace	AWS account	Notes
`env-ci`	`drive-apig-ci`	cross-account	CircleCI project, ECR, contexts
`env-dev`	`drive-apig-dev`	non-prod	Canonical resource definitions
`env-staging`	`drive-apig-staging`	non-prod	Symlinks from env-dev
`env-prod`	`drive-apig-prod`	prod	Symlinks from env-dev
`env-docs`	`drive-apig-docs`	(CF, no AWS infra)	Cloudflare Pages project

Backend

Remote state in Terraform Cloud (app.terraform.io), one workspace per env:

hcl

terraform {
  required_version = ">= 1.0.2"
  backend "remote" {
    organization = "drive-apig"
    workspaces { name = "drive-apig-dev" }
  }
}

Never local state.

Symlink convention

env-dev is canonical. env-staging/env-prod symlink main.<resource>.tf from env-dev:

bash

cd platform/terraform/env-prod
ln -s ../env-dev/main.apig.tf main.apig.tf

Per-env files (not symlinked):

main.tf — provider, backend, locals
variables.tf — env-specific defaults

Edit resource files in env-dev/; changes apply to all three envs. Env-specific behavior via variables, not duplicated files.

Providers

hcl

terraform {
  required_providers {
    aws     = { source = "hashicorp/aws",     version = "5.70.0" }
    random  = { source = "hashicorp/random",  version = "3.1.3" }
  }
}

env-docs adds Cloudflare (~> 4.0) — env-dev/staging/prod pin 3.x which lacks cloudflare_pages_project.

Resource groups (env-dev)

File	Resources
`main.apig.tf`	REST API, resources, deployment, stage, usage plan, API keys, custom domain + base path mapping
`main.waf.tf` + `main.waf.*.tf`	Web ACL, rule groups, IP sets, logging pipeline
`main.dynamodb.tf`	Shared tables (rate-limits, ssm-config)
`main.cloudwatch.tf`	Log groups, metric alarms
`main.cmstosocial.tf`	cmstosocial-specific resources