diff --git a/README.md b/README.md
index 3f66f6a..9fa43f5 100644
--- a/README.md
+++ b/README.md
@@ -198,6 +198,49 @@ Run the setup script to create the GCS offsite bucket, service account, and stor
 
 This creates the `sea-haven-backups` GCP project with a locked-retention GCS bucket. After running, configure the Storage Transfer job in the GCP Console using the AWS credentials from `forgejo/gcs-transfer-credentials`.
 
+## Infrastructure as Code (CDK)
+
+All AWS infrastructure is defined as an [AWS CDK](https://docs.aws.amazon.com/cdk/) v2 app written in TypeScript. There is no console-managed infrastructure — every resource in the sections above is synthesized from this repo.
+
+### Project layout
+
+| Path | Purpose |
+|------|---------|
+| `bin/app.ts` | CDK app entry point. Instantiates both stacks and wires the dependency between them. |
+| `lib/forgejo-stack.ts` | Main stack (`forgejo`, us-east-1): EC2 instance, security groups, IAM, ALB target/DNS, secrets, EBS data volume, DLM snapshots, and the backup-verification construct. Holds the `FORGEJO_VERSION` constant. |
+| `lib/forgejo-replica-stack.ts` | Replica stack (`forgejo-replica`, us-west-2): the S3 CRR replica bucket with versioning, Object Lock (Governance, 90d), and Glacier lifecycle. |
+| `lib/constructs/backup-verification.ts` | `BackupVerification` construct — the daily verification Lambda, its schedule, and CloudWatch alarms. |
+| `lambda/backup-verification/` | Python 3.12 handler (`app.py` + `requirements.txt`) bundled via `@aws-cdk/aws-lambda-python-alpha`. |
+| `scripts/gcp-setup.sh` | One-time GCP offsite bucket/service-account provisioning (see [GCP Offsite Setup](#gcp-offsite-setup-one-time)). |
+| `cdk.json` | CDK configuration — the `app` command and context feature flags. |
+| `cdk.context.json` | Cached context lookups (VPC + AMI), committed so synth is deterministic. |
+
+### Stacks
+
+The app defines two stacks, both pinned to account `328440206208` with explicit kebab-case `stackName`s:
+
+- **`forgejo-replica`** (us-west-2) — the S3 replica bucket. Deployed first; exports the replica bucket ARN and name.
+- **`forgejo`** (us-east-1) — the main stack. Consumes the replica bucket ARN/name and declares a dependency on `forgejo-replica`, so CDK always deploys the replica first.
+
+### `cdk.json`
+
+`cdk.json` is the CDK entry configuration, committed to the repo:
+
+- **`app`**: `npx ts-node bin/app.ts` — runs the TypeScript app directly (no separate `tsc` build step needed for synth).
+- **`watch`**: include/exclude globs for `cdk watch`.
+- **`context`**: CDK feature flags (e.g. `@aws-cdk/core:target-partitions`). Cached lookup context (VPC subnets, the AL2023 arm64 AMI) lives separately in `cdk.context.json` — `cdk.json` holds only feature flags.
+
+`aws-cdk-lib` is pinned to an exact version (no `^`/`~`) per the CDK version policy; Dependabot keeps it current.
+
+### Common commands
+
+```bash
+npm install
+npm run synth        # cdk synth  — emit CloudFormation without deploying
+npm run diff         # cdk diff   — diff local app against deployed stacks
+npm run deploy       # cdk deploy — deploy (pass -- --all for both stacks)
+```
+
 ## Deployment
 
 ```bash