engineering-handbook/confluence/06-aws-infrastructure.md

AWS Infrastructure

Infrastructure as code

• Every AWS resource is managed by infrastructure as code. Do not create Lambdas, roles, buckets, or anything else by hand in the console.
• Terraform (run by HCP Terraform) is the default for all new projects.
• Some existing projects use AWS SAM or AWS CDK. Keep working in the tool the project already uses. Do not start a new project on SAM or CDK without agreement from Sea Haven.
• Terraform creates the infrastructure. The CI/CD pipeline deploys the application code into it. Terraform does not package or deploy application code.

Lambda defaults

Every Lambda function uses these settings:

Setting	Value
Runtime	Python 3.12, or Node.js 24 (nodejs24.x)
Architecture	arm64
Log retention	60 days, set explicitly in code
Name	kebab-case, prefixed with the stack or repo name

• Always set log retention explicitly. The AWS default keeps logs forever.
• Do not start new functions on older Node runtimes such as nodejs22.x.
• Give each function an IAM role with only the permissions it needs. Never use AdministratorAccess or broad wildcards.

S3

• Tag every bucket with Purpose and ManagedBy.
• Define lifecycle policies in code.
• Use Glacier Deep Archive for archival data.

Outputs

Every stack exposes the function ARNs and any externally used URLs (such as API endpoints) as outputs.

Dependency versions

• Pin dependencies to exact versions and commit the lockfile.
• Automated dependency-update PRs keep those pins current. Do not disable them or add blanket ignore rules.
• If one specific release is broken, ignore only that release, with a comment explaining why.

README

Every repo has a README that accurately describes:

• Architecture
• Services and functions
• Data flow
• Required configuration

Update the README in the same PR that changes the behavior it describes.

Project layout (Terraform)

project-name/
├── terraform/          # Infrastructure (applied by HCP Terraform)
│   ├── bootstrap/      # Placeholder packages so Terraform can create functions
│   ├── lambda.tf
│   ├── s3.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── versions.tf
├── src/                # Application code (deployed by the pipeline)
├── .github/
│   └── workflows/
│       ├── ci.yaml
│       └── deploy-<name>.yaml
└── README.md

CI runs terraform fmt -check -recursive and terraform validate on every PR. Terraform plans for PRs run in HCP Terraform.