CDK Architecture Diagrams
Version: 2.0.0 | Last Updated: 2026-02-02 Spec Reference: specs/aws-sandbox/spec.md (Section 13) Plan Reference: specs/aws-sandbox/plan.md (Section 2.4)
Overview
This document provides architecture diagrams for the aws-sandbox npm package. Diagrams are generated using the Python diagrams library with native AWS icons for consistent, professional rendering across all platforms.
Diagram Generation:
- Source:
docs/sandbox/diagrams/*.py - Output:
static/images/architecture/*.png - Regenerate:
cd docs/docs/sandbox/diagrams && python generate_all.py
1. AWS Architecture (4-Stack Overview)
Shows the relationship between AccountPoolStack, IDCStack, DataStack, and ComputeStack across Hub Account and IDC Account.
Stacks:
- AccountPoolStack (Hub): AWS Organizations + OU management
- IDCStack (IDC Account): IAM Identity Center configuration
- DataStack (Hub): S3 Audit bucket, DynamoDB Registry
- ComputeStack (Hub): API Gateway + Lambda functions
2. Consumer E2E Flow (5-Layer Validation)
Shows the 5-layer validation process for consumer package testing.
Layers:
| Layer | Description | Validation |
|---|---|---|
| L1 | npm pack & install | Package integrity |
| L2 | CLI version check | Entrypoint works |
| L3 | synth --all | CDK synthesis |
| L4 | deploy --localstack | CloudFormation deploy |
| L5 | list-stacks | CREATE_COMPLETE |
3. 3-Tier Testing Pipeline
Shows the testing progression: Snapshot → LocalStack → Phase 3.5 → AWS.
Tiers:
| Tier | Tests | Time | Cost | Coverage |
|---|---|---|---|---|
| Tier 1: Snapshot | 29 | 2-3 sec | $0 | 70-80% |
| Tier 2: LocalStack | 11 | 30-60 sec | $0 | +15-20% |
| Phase 3.5: Consumer E2E | 5 Layers | 1-2h | $0 | BLOCKING |
| Tier 3: AWS Sandbox | All | 5-10 min | ~$50/mo | +5-10% |
4. Deployment Sequence (Phase-Based)
Shows the phased deployment order with dependencies.
Phases:
- Phase 1: AccountPoolStack (Organizations)
- Phase 2: IDCStack (requires AccountPoolOuId export)
- Phase 3: DataStack + ComputeStack (parallel, require IdentityStoreId)
5. npm Package Structure
Shows the package contents and consumer usage flow.
Package Contents:
aws-sandbox-0.3.18.tgz
├── bin/cli.js (entrypoint)
├── lib/ (compiled TypeScript)
├── source/infrastructure/dist/app.cjs (~58MB)
├── source/lambdas-bundled/*.zip
└── source/frontend/dist/ (React build)
6. ADLC 6+1 Phase Lifecycle
Shows the release workflow: PLAN → BUILD → TEST → Phase 3.5 → RELEASE.
Phases:
- PLAN: spec.md → plan.md → tasks.md (HITL Gate)
- BUILD: npm run build → build:consumer-app → app.cjs
- TEST: Tier 1 Snapshot → Tier 2 LocalStack
- Phase 3.5: Consumer E2E (L1-L5) - BLOCKING
- RELEASE: npm pack → HITL Approval → npm publish
7. Stack Resource Mapping
7.1 DataStack Resources (19 Resources)
| Resource | Type | Purpose |
|---|---|---|
| S3 Bucket | Storage | Audit logs (7yr SOX retention) |
| DynamoDB | Database | LeaseTable, Registry |
| AppConfig | Management | Feature flags |
| KMS Key | Security | Encryption at rest |
7.2 ComputeStack Resources (26 Resources)
| Resource | Type | Purpose |
|---|---|---|
| API Gateway | Network | HTTP API + JWT auth |
| Lambda (AccountVending) | Compute | Python 3.12 |
| Lambda (AccountCleaner) | Compute | Container-based |
| EventBridge | Integration | Daily cleanup schedule |
| CloudWatch | Management | Logs and alarms |
Cross-References
| Diagram | Related Document | Section |
|---|---|---|
| 4-Stack Overview | ARCHITECTURE.md | Section 1 |
| Consumer E2E Flow | tasks.md | T3.3 Flow of Events |
| 3-Tier Testing | spec.md | Section 3.2 NFR |
| Deployment Sequence | ARCHITECTURE.md | Section 3 |
| npm Package Structure | spec.md | FR-003 |
| ADLC Lifecycle | plan.md | Section 3 |
| Stack Resources | ARCHITECTURE.md | Section 2 |
Diagram Generation
Prerequisites
pip install diagrams
Generate All Diagrams
cd docs/docs/sandbox/diagrams
python generate_all.py
Individual Scripts
| Script | Output |
|---|---|
01_aws_4stack_architecture.py | 4-Stack overview |
02_consumer_e2e_flow.py | Consumer validation flow |
03_testing_pipeline.py | 3-Tier testing |
04_deployment_sequence.py | Phase-based deployment |
05_npm_package_structure.py | Package contents |
06_adlc_lifecycle.py | Release workflow |
07_datastack_resources.py | Data stack resources |
08_computestack_resources.py | Compute stack resources |
Version: 2.0.0 Created: 2026-02-02 Diagram Library: Python diagrams (mingrammer) v0.25.1 ADLC Phase: 1.2 (Technical Feasibility Assessment) Constitutional Compliance: CHK050 (SOPs Defined), RQ4 (Architecture Diagrams)