Architecture as version-controlled evidence
Generated architecture documentation
Turn a synthesized CDK assembly into Markdown that reviewers can read in GitHub, keep beside the code and regenerate whenever the estate changes. Everything is derived locally from CloudFormation and consumes no AI credits.
Generate the document
The default command synthesizes every stack and creates docs/cdk-architecture.md, including its parent directory when needed.
npx cdk-insights document
# Choose the destination and heading
npx cdk-insights document --file docs/platform/architecture.md --title "Checkout platform architecture"
# Reuse an assembly from an earlier pipeline step
npx cdk-insights document --no-synth --out-dir cdk.outWhat the file contains
Mermaid architecture graph
Logical resources and their explicit dependencies or CloudFormation references.
Estate summary
A service-by-service resource count across the synthesized stacks.
Stack inventory
A section for each stack with its synthesized resource total.
Attack-path review
Statically identifiable paths from public entry points to sensitive data resources, including severity and context.
Review notes
Clear limits explaining that template relationships do not prove runtime reachability.
Options
| Option | Default | What it controls |
|---|---|---|
| --no-synth | synth enabled | Generate from an existing cloud assembly without invoking the CDK app. |
| --out-dir <path> | cdk.out | Select the cloud assembly directory. |
| --file, -f <path> | docs/cdk-architecture.md | Choose the Markdown destination. Missing parent directories are created. |
| --title <text> | CDK Architecture | Set the top-level heading in the generated document. |
Keep it current in CI
Generate the file after synthesis and fail if the committed document is stale. This makes architecture changes visible in the same pull request as the CDK change.
- name: Synthesize CDK
run: npx cdk synth
- name: Regenerate architecture documentation
run: npx cdk-insights document --no-synth
- name: Check that documentation was committed
run: git diff --exit-code -- docs/cdk-architecture.mdReview the generated diagram
- GitHub and many documentation systems render Mermaid blocks directly.
- Resource relationships come from explicit dependencies and CloudFormation references.
- Public-to-sensitive paths are review leads, not proof that data is reachable.
- Validate IAM, resource policies, network controls and application authorisation together.