engineering-handbook/aws-infrastructure.md

# AWS Infrastructure

## IaC Strategy

- **SAM** is the default for new serverless stacks (Lambda + API Gateway + DynamoDB)
- **CDK** only for complex infrastructure (ECS, VPCs, multi-service compositions)
- Every deployed resource should be managed by CloudFormation
- No manually-created Lambdas, roles, or other resources outside of IaC

## Lambda Defaults

These apply to every Lambda in every project. Verify, don't assume.

| Setting | Value |
|---|---|
| Runtime | Python 3.12 or Node 24.x |
| Architecture | arm64 |
| Log retention | 60 days (explicit in IaC template) |
| Naming | kebab-case, matching the stack name prefix |

Never rely on the CloudWatch default for log retention. Always set `RetentionInDays` explicitly in the template.

## CDK Version Policy

Pin `aws-cdk-lib` to an exact version (no `^`, `~`, or `>=`) and let Dependabot keep it current. There is no static "blessed version" — the org standard is the latest release that passes the gates below. Do not add blanket `dependabot.yml` ignore entries for `aws-cdk-lib`; that is how pins rot into carrying known vulnerabilities.

Why exact + automated: the exact pin plus the lockfile gives reproducible builds; weekly Dependabot version updates keep the pin moving; CI (`npm ci` + `cdk synth`) and the dependency-review check reject a bad release at the PR. A release with broken bundled-dep metadata (e.g. 2.254.0) fails `npm ci` on its own bump PR; a release bundling a vulnerable transitive dep fails dependency review. Either way, a bad release never merges — the gates do the vetting, not a frozen number in this document.

aws-cdk-lib bundles transitive dependencies (`inBundle: true`) that npm `overrides` cannot patch. When a bundled dep has a vulnerability, the only fix is advancing to a release that bundles the patched version — treat the alert as a prompt to merge the next Dependabot bump, never as something to dismiss indefinitely.

If a specific release is known-bad, ignore that version only (`ignore: - dependency-name: aws-cdk-lib, versions: ["2.254.0"]`) with a comment explaining why, and remove the entry once a fixed release ships.

When upgrading, verify on a branch first:

1. Update `package.json` to the new version
2. Run `rm -rf node_modules package-lock.json && npm install`
3. Run `npm ci` — if it fails, the version is not safe
4. Run `npx cdk synth` — if it fails, the version is not safe

## CloudFormation Outputs

Every stack should export:

- Function ARNs
- Any externally-consumable URLs (API Gateway endpoints, etc.)

## S3

- Every non-CloudFormation bucket must have `Purpose` and `ManagedBy` tags
- Define lifecycle policies in the IaC template
- Use Glacier Deep Archive for archival data

## README

Every repo must have a README that accurately describes:

- Project architecture
- Lambdas and services
- Data flow
- Configuration requirements

Update the README in the same commit where functionality changes. If a README is missing or outdated when you start working on a project, fix it as part of the current work.