From 2d74f886bc4a9212c63028609e7a2a9a7317cb8a Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Fri, 10 Jul 2026 16:07:32 -0400
Subject: [PATCH] Document CDK app and cdk.json in README (#25)

The README described the sh-mcp-auth stack's contents but never
documented that the repo root is a CDK app or what cdk.json is.
Add an Infrastructure (CDK app) section covering the cdk.json app
config, the infra/bin/app.ts entry point, the stacks, deploy-time
context inputs, and synth/deploy commands, and list cdk.json and
infra/ in the layout so the IaC component is discoverable.
---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/README.md b/README.md
index 43005e8..c3abd3a 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,48 @@ The canonical map of Sea Haven's AWS infrastructure lives in Confluence. This pr
 
 - **[AWS Architecture Map](https://seahaven.atlassian.net/wiki/spaces/IT/pages/1540098)** (Confluence, IT space, page 1540098)
 
+## Infrastructure (CDK app)
+
+All AWS infrastructure is defined as code with the **AWS CDK** (TypeScript, `aws-cdk-lib` pinned
+in `package.json`). The repo root is the CDK app: `cdk.json` is the app config and points the CDK
+CLI at the app entry point.
+
+```jsonc
+// cdk.json
+{
+  "app": "tsx infra/bin/app.ts", // entry point (run with tsx, no pre-compile)
+  "output": "cdk.out",           // synth output dir (git-ignored)
+  "context": { "@aws-cdk/core:newStyleStackSynthesis": true }
+}
+```
+
+- **Entry point** — `infra/bin/app.ts` constructs the `App` and instantiates the stacks. Every
+  stack sets an explicit kebab-case `stackName` and pins `env` to account `328440206208` /
+  `us-east-1`, so synth needs no AWS credentials (shared CMKs are referenced by ARN, not
+  `fromLookup`).
+- **Stacks** — `infra/lib/`. Currently one: `ShMcpAuthStack` → **`sh-mcp-auth`** (the Cognito auth
+  substrate, detailed below). The per-tier `sh-mcp-ops` / `sh-mcp-finance` hosting stacks join the
+  same app in Phase 2b. The Lambda handler source the stacks bundle lives in `auth/` (and later
+  `servers/` / `jobs/`), not under `infra/`.
+- **Deploy-time context** — the app reads two optional `-c` context inputs: `callbackUrls`
+  (per-tier OAuth callback URLs; defaults to a placeholder until the conversational surface is
+  chosen) and `logsKmsArn` (the `alias/seahaven-logs` CMK for the Lambda log groups; AWS-managed
+  encryption is used if absent).
+
+```bash
+# from the repo root
+npm ci
+npx cdk synth                         # synthesize CloudFormation into cdk.out/
+npx cdk diff  sh-mcp-auth             # preview changes against the deployed stack
+npx cdk deploy sh-mcp-auth \
+  -c logsKmsArn=<cmk-arn> \
+  -c callbackUrls='["https://…/oauth/callback"]'
+```
+
+CI runs `npx cdk synth` at the repo root on every PR (the `ci-typescript-cdk` reusable workflow with
+`run-cdk-synth: true`); merges to `main` deploy via the `cd-cdk` reusable workflow over the
+per-repo `githubdeploy-sh-mcp` OIDC role. **Nothing is deployed to AWS yet** — see status above.
+
 ## Auth substrate (Phase 2a — `infra/` + `auth/`)
 
 `infra/` is the root CDK app; `cdk synth` builds the **`sh-mcp-auth`** stack:
@@ -75,6 +117,8 @@ groups is supplied at deploy via `-c logsKmsArn=...`.
 ## Layout (target)
 
 ```
+cdk.json    CDK app config (app → infra/bin/app.ts)
+infra/      CDK app: bin/app.ts entry + lib/ stack definitions
 packages/   shared + one package per integration
 servers/    sh-mcp-ops, sh-mcp-finance  (CDK stacks)
 auth/       cognito, pre-token-lambda, group-sync-lambda