adam bien's blog

AWS CDK Infrastructure as Business Components (BCE/ECB) with the /aws-cdk Skill 📎

The /aws-cdk skill generates and reviews Java AWS CDK v2 projects organized as BCE (Boundary-Control-Entity) business components. Infrastructure code follows the same structure as a business application instead of accumulating as a flat list of resources. It ships as an AIrails skill: /aws-cdk.

The main tenet is the separation of stacks from constructs. A stack decides which resources deploy together and lives in boundary. A construct defines how a capability is configured, is reusable across stacks, and lives in control as a stateless factory, preferably an interface with static methods. Immutable data that describes infrastructure without creating it, like build specs and typed value objects, lives in entity.

The remaining ideas follow from that split:

  1. Packages are business components named after the AWS capability they provision: s3, cloudfront, cognito, route53, stepfunctions. A component spanning multiple services is named after its domain responsibility.
  2. A single CDKApp entry point loads configuration as typed Java records, applies tags, wires stacks in dependency order, and calls app.synth(). Stacks never read CDK context or environment variables; they receive typed records.
  3. Regions are pinned in a central Stacks interface exposing StackProps constants. Account and region are never inlined in stack classes.
  4. Stacks stay independent. A producing stack passes resource interfaces like IBucket or ITable to consumers, never stack instances.
  5. For IAM, grant* methods on the target construct generate least-privilege policies. Explicit PolicyStatements are the fallback.
  6. Synthesis stays deterministic and side-effect free: no SDK calls, no timestamps, no randomness during construction. Tests assert on the synthesized CloudFormation template instead of snapshots.

The skill composes with /bce and /java-conventions and ships with a domain-neutral project blueprint. It is also compatible with /sbce, the spec-driven BCE workflow: a capability spec describes one business component, and the code is iterated until it matches the spec. A compilable starter is available at AdamBien/aws-cdk-plain, and constructions.cloud collects example constructs and CDK applications.