From 5ecd5960cb851b3cf01c74ee7dac02825795c587 Mon Sep 17 00:00:00 2001
From: Adam Moussa <adam@seahavenind.com>
Date: Fri, 10 Jul 2026 15:56:38 -0400
Subject: [PATCH] Document CDK app layout in README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README covered the deployed AWS resources but never described the
CDK app itself — the cdk.json manifest, the bin/lib entry points, and
the committed context cache. Add a "CDK app" section so the
infrastructure-as-code component is documented alongside the resources
it provisions.

Refs: INFRA-12
---
 README.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/README.md b/README.md
index 5016b3b..3b5fadc 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,25 @@ office UniFi devices ──syslog/514──▶ EIP 184.72.154.32 ──▶ EC2 (
 | Log group | `unifi-syslog` (90-day retention) — created/retained by the CW agent, **not** a CFN resource (holds history; see stack comment) |
 | Alarm | `Syslog-NoIncomingLogs` — `IncomingLogEvents` Sum < 1 over 2×1-day, ALARM-only → `site-alerts` |
 
+## CDK app
+
+Infrastructure is a single-stack AWS CDK app written in TypeScript. `cdk.json` is
+the app manifest the CDK CLI reads on every command: its `app` entry
+(`npx tsx bin/app.ts`) runs the TypeScript entry point directly through `tsx`, so
+`synth`/`deploy` need no separate `tsc` compile step. The file also carries the
+`watch` globs (for `cdk watch`) and the CDK feature-flag `context`.
+
+| Path | Role |
+|---|---|
+| `cdk.json` | CDK app manifest — `app` entry command, `watch` globs, feature-flag context |
+| `bin/app.ts` | App entry point; instantiates `SyslogServerStack` with explicit `stackName: "syslog-server"` and env pinned to account `328440206208` / `us-east-1` |
+| `lib/syslog-server-stack.ts` | The `syslog-server` stack — every resource in the table above (EC2 instance + rsyslog/CloudWatch/NetFlow user-data, security group, IAM role, EIP association, alarms) |
+| `cdk.context.json` | Cached provider lookups — the VPC (`vpc-0d3d4b67bd0cf8a68`) and the pinned AL2023 AMI (`cachedInContext`); committed so synth is deterministic |
+
+`aws-cdk-lib` is pinned to an exact version (`2.261.0`). The npm scripts wrap the
+CDK CLI — `npm run synth`, `npm run diff`, `npm run deploy` — plus
+`npm run build` (`tsc` type-check).
+
 ## Documentation
 
 The canonical map of Sea Haven's AWS infrastructure lives in Confluence. This project's `syslog-server` stack is represented there as a Mermaid subgraph.