This project is an advanced AWS Cloud Development Kit (CDK) template designed for enterprise-grade scalability, clean separation of concerns, and multi-environment deployments. It uses a structured three-stack architecture to organize resources effectively.
The infrastructure is broken down into three distinct stacks per environment to reduce blast radius and manage state safely.
The Stateful Stack is responsible for resources that hold persistent data. These resources are typically the hardest to recreate and should have strict deletion policies.
- Examples: Amazon DynamoDB, Amazon RDS, Amazon S3 (Data/Assets), Amazon Cognito User Pools.
- Why separate?: Changes to stateless resources (like a Lambda function) should never accidentally impact or delete stateful resources. You deploy this stack less frequently.
The Stateless Stack holds ephemeral resources or resources that can be easily recreated from source code without data loss.
- Examples: AWS Lambda functions, Amazon API Gateway, AWS AppSync, ECS Tasks.
- How it connects: The Stateless Stack receives references (like table ARNs or bucket names) from the Stateful Stack via stack props. This prevents hardcoding ARNs and ensures tight coupling where needed.
The Global Stack is used for resources that span multiple regions or are tied to edge locations. This stack is typically deployed to us-east-1 regardless of where the rest of your infrastructure lives.
- Examples: Amazon CloudFront distributions, AWS WAF (Web Application Firewall) attached to CloudFront, ACM (AWS Certificate Manager) certificates for CloudFront.
- How it connects: The Global stack usually needs the API Gateway endpoint or S3 Website Bucket (from the Stateless or Stateful stacks) to set up CloudFront origins.
├── bin/
│ ├── cdk-template-bren.ts # Main entry point for the CDK application
│ └── environments/ # Logic to stitch the 3 stacks together per env
│ ├── base.ts # Core logic to wire Stateful -> Stateless -> Global
│ ├── dev.ts # Setup dev environment
│ ├── staging.ts # Setup staging environment
│ └── prod.ts # Setup production environment
├── configs/ # Environment-specific configuration values
│ ├── dev.ts # e.g. "template-dev", open CORS origins
│ ├── staging.ts # e.g. "template-staging"
│ └── prod.ts # e.g. "template-prod", strict CORS origins
├── lib/
│ ├── global/ # Global Stack definition
│ │ └── constructs/ # Global constructs (e.g., CloudFront, WAF)
│ ├── stateful/ # Stateful Stack definition
│ │ └── constructs/ # Stateful constructs (e.g., S3, DynamoDB, Cognito)
│ ├── stateless/ # Stateless Stack definition
│ │ └── constructs/ # Stateless constructs (e.g., Lambda, API Gateway)
│ └── types/ # Shared TypeScript interfaces (e.g., StackProps)
Within each stack directory (lib/global, lib/stateful, lib/stateless), you will find a constructs/ subdirectory. This is where you define your reusable AWS resource groupings (L3 constructs).
- Purpose: Instead of declaring all AWS resources directly within the stack file, you create modular, purpose-built
Constructclasses. EachConstructencapsulates a set of related AWS resources and their configurations. - Benefits:
- Modularity & Reusability: Easily reuse resource patterns across different parts of your application or even different projects.
- Clear Ownership: Each construct is responsible for a specific set of functionality (e.g., a
S3Constructhandles all S3 buckets for the stack, aDynamoDbConstructhandles DynamoDB tables). - Maintainability: Changes to a specific resource type are isolated within its construct file, making updates safer and easier to manage.
- Testability: Custom constructs are easier to unit test in isolation.
- Example (
lib/stateful/constructs/s3.ts): TheS3Constructin the stateful stack handles the creation and configuration of S3 buckets (dataBucketandassetsBucket). It demonstrates how to apply environment-specific logic (e.g.,removalPolicy) and expose public properties for other constructs or stacks to reference.
Environments are defined in configs/ and instantiate the stacks via bin/environments/.
- Configuration (
configs/dev.ts): Defines values specific to an environment (likestage: 'dev', account IDs, regions, specific feature flags, or CORS origins). - Environment Setup (
bin/environments/dev.ts): Takes the configuration and passes it intosetupEnvironmentinbase.ts. - The Base Wiring (
bin/environments/base.ts): This is the heart of the cross-stack communication. It creates theStatefulStack, and then creates theStatelessStack, passing the necessary constructs (like databases or buckets) from the stateful stack directly into the stateless stack's properties.
If you create an S3 bucket in StatefulStack, you expose it as a public property on the class:
// lib/stateful/stateful-stack.ts
public dataBucket: s3.IBucket;Then, in bin/environments/base.ts, you pass it to the Stateless Stack:
// bin/environments/base.ts
dataBucket: statefulStack.dataBucket,To deploy a specific environment, target its specific stacks.
For development:
npx cdk deploy "template-dev-*"For production:
npx cdk deploy "template-prod-*"(Note: The template-dev prefix is defined by the stage variable in the respective config file).
npm run buildcompile typescript to jsnpm run watchwatch for changes and compilenpm run testperform the jest unit testsnpx cdk diffcompare deployed stack with current statenpx cdk synthemits the synthesized CloudFormation template