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.
Add engineering handbook Conventions covering naming, git workflow, commit messages, pull requests, code review, GitHub standards, AWS infrastructure, SAM project layout, and secrets management. Commit messages section adapted from RomuloOliveira/commit-messages-guide (CC-BY-4.0). 2026-05-02 16:42:44 -04:00			`# 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 \|`
			`\|---\|---\|`
Add CDK version policy, update Node 24 and GitHub Actions CI/CD (#6) * Update CDK version policy, Node 24 runtime, and GitHub Actions CI/CD - Pin blessed aws-cdk-lib version (2.253.1) with upgrade procedure - Update Lambda runtime default from Node 22 to Node 24 - Rewrite CI/CD page to reflect GitHub Actions reusable workflows (was still referencing CodePipeline/CodeBuild) * Add pre-push hook for npm ci validation Catches lock file drift locally before it breaks CI. Includes install instructions in git-workflow.md. * Add repo provisioning script Automates the new-repo checklist: GitHub repo creation, OIDC deploy role, repo secret, security features, CI/CD workflow stubs, and pre-push hook installation. Supports both SAM and CDK stack types. * Add shared VpnEc2Instance CDK construct Reference construct for the VPN-accessible EC2 pattern used by file-share and forgejo. Includes VPC/subnet lookup, SG, IAM role, encrypted EBS, and DLM snapshots. Copy into lib/constructs/. * Add post-deploy health check template Template script for project-specific health checks. Copy to scripts/health-check.sh — CD workflows run it automatically. 2026-05-14 18:39:13 -04:00			`\| Runtime \| Python 3.12 or Node 24.x \|`
Add engineering handbook Conventions covering naming, git workflow, commit messages, pull requests, code review, GitHub standards, AWS infrastructure, SAM project layout, and secrets management. Commit messages section adapted from RomuloOliveira/commit-messages-guide (CC-BY-4.0). 2026-05-02 16:42:44 -04:00			`\| 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.

Add CDK version policy, update Node 24 and GitHub Actions CI/CD (#6) * Update CDK version policy, Node 24 runtime, and GitHub Actions CI/CD - Pin blessed aws-cdk-lib version (2.253.1) with upgrade procedure - Update Lambda runtime default from Node 22 to Node 24 - Rewrite CI/CD page to reflect GitHub Actions reusable workflows (was still referencing CodePipeline/CodeBuild) * Add pre-push hook for npm ci validation Catches lock file drift locally before it breaks CI. Includes install instructions in git-workflow.md. * Add repo provisioning script Automates the new-repo checklist: GitHub repo creation, OIDC deploy role, repo secret, security features, CI/CD workflow stubs, and pre-push hook installation. Supports both SAM and CDK stack types. * Add shared VpnEc2Instance CDK construct Reference construct for the VPN-accessible EC2 pattern used by file-share and forgejo. Includes VPC/subnet lookup, SG, IAM role, encrypted EBS, and DLM snapshots. Copy into lib/constructs/. * Add post-deploy health check template Template script for project-specific health checks. Copy to scripts/health-check.sh — CD workflows run it automatically. 2026-05-14 18:39:13 -04:00			`## 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

Add engineering handbook Conventions covering naming, git workflow, commit messages, pull requests, code review, GitHub standards, AWS infrastructure, SAM project layout, and secrets management. Commit messages section adapted from RomuloOliveira/commit-messages-guide (CC-BY-4.0). 2026-05-02 16:42:44 -04:00			`## 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.`