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)
- **Migrating stacks** from mgmt into seahaven-prod / seahaven-dev use **HCP Terraform** (migrate-and-convert; do not convert in place in mgmt). The authoritative per-stack steps live in the `seahaven-org-baseline` README migration checklist (plan/apply role patterns, boundary widen, artifact packaging, cutover). Reference implementation: `afi-backup-monitor` (PLAT-56).
- Every deployed resource should be managed by IaC (CloudFormation via SAM/CDK, or HCP Terraform state for migrated stacks)
- No manually-created Lambdas, roles, or other resources outside of IaC

## HCP Terraform VCS file triggers

New prod/dev HCP workspaces follow the first-apply runbook in `seahaven-org-baseline`. When the workspace is created, set VCS file triggers before the first merge to the tracked branch.

- Keep `file-triggers-enabled`. Do not turn file triggers off so that docs-only commits skip prod applies.
- `trigger-prefixes` are added to the working directory. `trigger-patterns` replace the working-directory filter and must include a glob for that directory.
- If the plan reads files outside the working directory (Lambda source, layers, `requirements.txt`, build scripts that copy `src/`, `functions/`, `lambda/`, or `lambdas/`), list those paths in `trigger-prefixes` or `trigger-patterns`. An empty pair with `working-directory=terraform` queues runs only for `terraform/` changes, so a source-only merge is ingested and then silently skipped.
- Record the live prefixes or patterns in the app README next to the workspace name.
- `python3 scripts/check_hcp_workspace_triggers.py` in `seahaven-org-baseline` lists file-triggered workspaces in `seahaven-mgmt`, `seahaven-prod`, and `seahaven-dev` and flags an empty prefix/pattern pair when the repo working directory references those source trees.

## Lambda Defaults

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

| Setting | Value |
|---|---|
| Runtime | Python 3.12 or Node 24.x (`nodejs24.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.

### Node runtime

This is the canonical statement; [dev-environment.md](dev-environment.md#nodejs) and [cdk-project-layout.md](cdk-project-layout.md#lambda-defaults) defer to it.

- **`nodejs24.x` is the standard.** Every new Node Lambda targets it, set explicitly in the IaC template.
- **`nodejs22.x` is legacy only.** It is valid for functions that already run on it, and those move to 24.x before the AWS deprecation date of 2027-04-30. Do not start a new function on it.
- **Never target `nodejs26.x`,** including once AWS ships it. Lambda applies runtime updates automatically, so a fresh major is only adopted after it has been generally available on Lambda for a full quarter, and only by a deliberate change to this page. Odd majors (25.x, 27.x) never become Lambda runtimes at all.

## 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.