From ce3833c3a4ff5d76f8ed0cfd21c186643579feab Mon Sep 17 00:00:00 2001 From: Adam Moussa Date: Fri, 10 Jul 2026 15:56:18 -0400 Subject: [PATCH] Document CDK app and cdk.json in README The README covered the deployed controls, config inputs, and CI/CD but never explained that the repo is a CDK app or what cdk.json does. Add a CDK app section describing the cdk.json entry point, project layout (bin/app.ts and the lib/ constructs), and the local synth/diff/deploy workflow so contributors can orient without reading the source. --- README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/README.md b/README.md index 18f365e..47b63c6 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,36 @@ Single stack `seahaven-external-dev-baseline`: - **No WAF, SES monitoring, Bedrock logging, DynamoDB CMK, or AWS Backup** — all production-only concerns in the source baseline. +## CDK app + +This repo is an AWS CDK application (TypeScript). `cdk.json` is the CDK +entry point: it sets `app` to `npx ts-node bin/app.ts`, so the CLI runs the +TypeScript source directly with no separate build step, and pins the CDK +feature flags / context the stack synthesizes against. + +Layout follows the standard CDK project structure: + +| Path | Purpose | +|---|---| +| `cdk.json` | CDK config — `app` command, `watch` globs, and feature-flag context | +| `bin/app.ts` | App entry point; instantiates the stack with explicit `stackName`, target account `396287094661`, and `us-east-1`, and reads `flowLogVpcIds` from context | +| `lib/external-dev-baseline-stack.ts` | The `seahaven-external-dev-baseline` stack; composes the constructs below | +| `lib/detective-controls.ts` | AWS Config, GuardDuty, Security Hub (FSBP + CIS v3.0), IAM Access Analyzer | +| `lib/flow-logs.ts` | VPC flow-logs bucket and (when VPC ids are supplied) flow logs | +| `lib/governance-toggles.ts` | Monthly cost Budget and alert subscriptions | + +Local workflow (from the repo root): + +```bash +npm ci +npx cdk synth # synthesize CloudFormation (also `npm run synth`) +npx cdk diff # diff against the deployed stack (`npm run diff`) +npx cdk deploy # deploy (`npm run deploy`) +``` + +`cdk.json` is committed; `cdk.out/` (synth output) and compiled `*.js` / +`*.d.ts` artifacts are git-ignored. + ## Configuration | Input | Where | Value | -- 2.50.1