diff --git a/README.md b/README.md
index 1fa174f..5890599 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,54 @@ Yealink T54W/T58W → HTTPS GET (?token=) → API Gateway (token authorizer) →
 - **SSM Parameter Store** — stores the Elements API key, auth token, door ID, and phone IPs
 - **Secrets Manager** — stores the Yealink phone admin password
 - **Custom Domain** — `doorunlock.seahaven.com` via Route 53 + ACM wildcard cert
+- **CloudWatch alarms** — one error alarm per Lambda (unlock, lockdown, authorizer, poller); each fires on `Errors > 0` and notifies the cross-stack `site-alerts` SNS topic (ALARM state only)
+
+## Infrastructure (CDK)
+
+All infrastructure is defined as code with the **AWS CDK v2 (TypeScript)**; `aws-cdk-lib` is pinned to `2.261.0`. The whole system is a single CloudFormation stack.
+
+### Layout
+
+```
+bin/app.ts                    # CDK app entry point
+lib/door-unlock-stack.ts      # DoorUnlockStack — all resource definitions
+lambda/
+├── unlock/unlock-handler.ts        # Unlock Lambda
+├── lockdown/lockdown-handler.ts    # Lockdown Lambda
+├── poller/lockdown-poller.ts       # Lockdown Poller Lambda
+└── authorizer/authorizer-handler.ts # Token authorizer Lambda
+cdk.json                      # CDK config (app command, watch, context flags)
+```
+
+### `bin/app.ts`
+
+Instantiates `DoorUnlockStack` with an explicit `stackName` of `seahaven-door-unlock-api`, pinned to account `328440206208` / `us-east-1`.
+
+### `lib/door-unlock-stack.ts`
+
+Defines every resource the stack owns:
+
+- The four Lambda functions (Node 24.x, arm64, 60-day log retention), bundled from TypeScript with esbuild
+- The HTTP API (`door-unlock-api`), its `GET /unlock`, `GET /lockdown`, and `GET /lockdown/status` routes, throttling, and JSON access logging
+- The `HttpLambdaAuthorizer` token authorizer (identity source `$request.querystring.token`, 5-minute result cache)
+- The EventBridge rule that invokes the poller once a minute, plus the poller's VPC config and security group (imported VPC/subnets, egress to the Elements API and phone LAN)
+- The custom domain, ACM certificate import, and Route 53 A record for `doorunlock.seahaven.com`
+- Imports of the SSM parameters, the phone-password secret, and the `site-alerts` SNS topic, with the corresponding `grantRead` IAM permissions
+- The four per-Lambda CloudWatch error alarms
+
+### `cdk.json`
+
+CDK configuration committed to the repo. The `app` command runs `npx tsx bin/app.ts`, so the TypeScript entry point executes directly via `tsx` (no separate compile step). It also carries the `watch` include/exclude globs and the CDK feature-flag `context`.
+
+### Commands
+
+```bash
+npx cdk synth   # synthesize the CloudFormation template
+npx cdk diff    # diff against the deployed stack
+npx cdk deploy  # deploy (see Manual Deployment below)
+```
+
+The same commands are also exposed as npm scripts (`npm run synth`, `npm run diff`, `npm run deploy`).
 
 ## Documentation