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 a known-good version. The current blessed version is **2.253.1**.

Why: aws-cdk-lib bundles transitive dependencies (`inBundle: true`). Certain versions (e.g., 2.254.0) break `npm ci` with phantom missing-package errors. npm `overrides` cannot fix bundled deps. Always test `npm ci` locally before pushing a version bump.

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.