aws-cdk-cloud-architecture

name	aws-cdk-cloud-architecture
metadata	{"category":"Multi-Cloud Architecture (AWS and Azure)"}
description	Provision multi-tier, enterprise-grade cloud infrastructure on AWS using AWS CDK v2 (TypeScript). Triggers when designing or implementing AWS CDK stacks, L3 constructs, multi-region networking (VPC, Transit Gateway), ECS Fargate microservices, serverless architectures (Lambda, EventBridge, DynamoDB), IAM least-privilege, CDK Aspects compliance checks, or CDK Pipelines CI/CD.
compatibility	AWS CDK v2 (>= 2.100.0), Node.js (>= 18.x), TypeScript (>= 5.0), AWS CLI v2

AWS CDK Cloud Architecture

Production-ready architectural patterns, L3 construct patterns, and TypeScript implementations for provisioning enterprise infrastructure using AWS Cloud Development Kit (CDK) v2.

---

1. Core Architecture Principles & Folder Structure

Recommended Project Layout

├── bin/
│   └── app.ts                  # App entrypoint & stack instantiation per environment
├── lib/
│   ├── aspects/                # CDK Aspects (compliance, tagging, security guards)
│   │   └── security-aspect.ts
│   ├── constructs/             # Modular L3 custom constructs
│   │   ├── network-construct.ts
│   │   ├── ecs-service-construct.ts
│   │   └── database-construct.ts
│   └── stacks/                 # Stack definitions
│       ├── network-stack.ts
│       ├── application-stack.ts
│       └── pipeline-stack.ts
├── config/                     # Environment configuration schemas
│   ├── dev.json
│   └── prod.json
├── cdk.json
├── package.json
└── tsconfig.json

---

2. Bootstrapping & Environment Configuration

Environment Configuration Pattern

Always use typed configuration objects instead of hardcoded values or raw process.env lookups inside constructs.

// config/environment.ts
export interface EnvironmentConfig {
  readonly account: string;
  readonly region: string;
  readonly environment: 'dev' | 'staging' | 'prod';
  readonly vpcCidr: string;
  readonly maxAzs: number;
  readonly ecsDesiredCount: number;
}

export const envConfigs: Record<string, EnvironmentConfig> = {
  dev: {
    account: '111111111111',
    region: 'us-east-1',
    environment: 'dev',
    vpcCidr: '10.0.0.0/16',
    maxAzs: 2,
    ecsDesiredCount: 2,
  },
  prod: {
    account: '222222222222',
    region: 'us-east-1',
    environment: 'prod',
    vpcCidr: '10.100.0.0/16',
    maxAzs: 3,
    : ,
  },
};

---

3. Production Multi-Tier Network & Core Constructs

Multi-AZ Secure VPC Construct (lib/constructs/network-construct.ts)

import { Construct } from 'constructs';
import * as ec2 from 'aws-cdk-lib/aws-ec2';

export interface NetworkConstructProps {
  readonly vpcCidr: string;
  readonly maxAzs: number;
}

export class NetworkConstruct extends Construct {
  public readonly vpc: ec2.IVpc;

  constructor(scope: Construct, id: string, props: NetworkConstructProps) {
    super(scope, id);

    this.vpc = new ec2.Vpc(this, 'ProductionVpc', {
      ipAddresses: ec2.IpAddresses.cidr(props.vpcCidr),
      maxAzs: props.maxAzs,
      natGateways: props.maxAzs, // High Availability across all AZs
      subnetConfiguration: [
        {
          cidrMask: ,
          : ,
          : ec2..,
        },
        {
          : ,
          : ,
          : ec2..,
        },
        {
          : ,
          : ,
          : ec2..,
        },
      ],
      : ,
      : ,
    });

    
    ..();
  }
}

---

4. Production Microservice Infrastructure (ECS Fargate + ALB + Aurora)

Application & Database Stack (lib/stacks/application-stack.ts)

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as ecsPatterns from 'aws-cdk-lib/aws-ecs-patterns';
import * as rds from 'aws-cdk-lib/aws-rds';
import * as kms from 'aws-cdk-lib/aws-kms';
import * as logs from 'aws-cdk-lib/aws-logs';
import { EnvironmentConfig } from '../../config/environment';

export interface ApplicationStackProps extends cdk.StackProps {
  readonly config: EnvironmentConfig;
  readonly vpc: ec2.IVpc;
}

export class ApplicationStack extends cdk.Stack {
  constructor() {
    (scope, id, props);

     { config, vpc } = props;

    
     kmsKey =  kms.(, , {
      : ,
      : ,
      : config. ===  ? cdk.. : cdk..,
    });

    
     dbCluster =  rds.(, , {
      : rds..({
        : rds..,
      }),
      : rds..(, {
        : ,
      }),
      : ,
      : ,
      vpc,
      : { : ec2.. },
      : ,
      kmsKey,
      : ,
      : config. ===  ? cdk.. : cdk..,
    });

    
     ecsCluster =  ecs.(, , {
      vpc,
      : ,
    });

    
     fargateService =  ecsPatterns.(, , {
      : ecsCluster,
      : ,
      : ,
      : config.,
      : { : ec2.. },
      : ,
      : {
        : ecs..(),
        : ,
        : ,
        : ecs..({
          : ,
          : logs..,
        }),
        : {
          : config.,
          : dbCluster..,
        },
        : {
          : ecs..(dbCluster.!),
        },
      },
    });

    
    dbCluster..(fargateService.);

    
     autoScaling = fargateService..({
      : config.,
      : config. * ,
    });

    autoScaling.(, {
      : ,
      : cdk..(),
      : cdk..(),
    });
  }
}

---

5. Security & Governance with CDK Aspects

Enforce organizational compliance rules (e.g., mandatory tags, SSL enforcement, encryption) across all stacks automatically.

Security Compliance Aspect (lib/aspects/security-aspect.ts)

import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
import { IConstruct } from 'constructs';

export class SecurityComplianceAspect implements cdk.IAspect {
  public visit(node: IConstruct): void {
    // Rule 1: Ensure all S3 buckets enforce SSL and encrypt at rest
    if (node instanceof s3.CfnBucket) {
      if (!node.bucketEncryption) {
        cdk.Annotations.of(node).addError('S3 Bucket must have encryption enabled.');
      }
    }
  }
}

// In bin/app.ts:
// cdk.Aspects.of(app).add(new SecurityComplianceAspect());

---

6. Self-Mutating CI/CD Pipeline (CDK Pipelines)

CDK Pipeline Stack (lib/stacks/pipeline-stack.ts)

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { CodePipeline, CodePipelineSource, ShellStep } from 'aws-cdk-lib/pipelines';

export class PipelineStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const pipeline = new CodePipeline(this, 'CdkPipeline', {
      pipelineName: 'EnterpriseCdkPipeline',
      synth: new ShellStep('Synth', {
        input: CodePipelineSource.gitHub('my-org/my-cdk-repo', 'main'),
        commands: [
          'npm ci',
          'npm run build',
          'npx cdk synth',
        ],
      }),
    });
  }
}

---

7. Best Practices & Production Checklist

1. Construct Immutability: Always pass CDK L2/L3 constructs by interface (IVpc, IBucket) rather than concrete types when referencing across stacks.
2. Deletion Policies: Use RemovalPolicy.RETAIN for production S3 buckets, DynamoDB tables, and Aurora clusters. Use RETAIN_ON_UPDATE_OR_DELETE for critical KMS keys.
3. Deterministic Deployments: Pin CDK npm package versions strictly ("aws-cdk-lib": "2.120.0") to avoid version drift between developer workstations and CI/CD pipelines.
4. Context & Caching: Commit cdk.context.json to source control to lock AZ lookup responses and prevent non-deterministic stack synthesis.