# aws/aws-cdk architecture

> Architecture diagram of the GitHub repository aws/aws-cdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws/aws-cdk
- Repository: https://github.com/aws/aws-cdk

## Overview

AWS CDK lets developers define infrastructure as reusable constructs composed into stacks and apps, then use the CDK CLI to synthesize CloudFormation templates, deploy stacks, and compare changes. The repository includes a broad construct library, including service-specific APIs, plus higher-level deployment pipelines. The graph emphasizes that documented user workflow and sampled pipeline behavior; many individual service implementations are represented by their enclosing directories. Edges cite the README or source-index references shown here, not unsampled implementation details.

Main entry points: [`packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts`](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts) (CDK Pipelines), [`packages/aws-cdk-lib`](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib) (Service constructs), [`packages/aws-cdk-lib/core`](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/core) (Constructs), [`packages/aws-cdk-lib/aws-codepipeline/lib/pipeline.ts`](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-codepipeline/lib/pipeline.ts) (CodePipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Infrastructure authoring"]
  node_constructs["Constructs"]
  node_stacks["Stacks"]
  node_cdkapp["CDK app"]
end

subgraph group_services["AWS constructs"]
  node_serviceconstructs["Service constructs"]
  node_rdsengines["RDS engines<br/>[engine.ts]"]
  node_pipeline["CodePipeline<br/>[pipeline.ts]"]
  node_pipelineactions["CloudFormation actions"]
  node_imagepipeline["Image Builder pipeline<br/>[image-pipeline.ts]"]
  node_redshiftquery["Redshift query<br/>[database-query.ts]"]
end

subgraph group_synthesis["Synthesis and deployment"]
  node_cli["CDK CLI"]
  node_cloudassembly["Cloud assembly<br/>[file-set.ts]"]
  node_cloudformation["CloudFormation"]
  node_deployedstack["Deployed stack"]
end

subgraph group_internals["Pipeline internals"]
  node_pipelinegraph["Pipeline graph<br/>[pipeline-graph.ts]"]
  node_cdkpipeline["CDK Pipelines<br/>[codepipeline.ts]"]
  node_artifactmap["Artifact mapping<br/>[artifact-map.ts]"]
  node_buildfactory["Build factory"]
  node_corepipeline["Pipeline base<br/>[pipeline-base.ts]"]
end

node_developer(("Developer"))

node_developer -->|"defines"| node_constructs
node_constructs -->|"compose into"| node_stacks
node_stacks -->|"form"| node_cdkapp
node_developer -->|"interacts with"| node_cli
node_cli -->|"synthesizes"| node_cdkapp
node_cli -->|"deploys through"| node_cloudformation
node_cli -->|"diffs against"| node_deployedstack
node_constructs -->|"use library"| node_serviceconstructs
node_serviceconstructs -.->|"includes"| node_rdsengines
node_serviceconstructs -.->|"includes"| node_pipeline
node_serviceconstructs -.->|"includes"| node_imagepipeline
node_serviceconstructs -.->|"includes"| node_redshiftquery
node_pipeline -->|"accepts actions"| node_pipelineactions
node_cdkpipeline -->|"translates graph"| node_pipelinegraph
node_cdkpipeline -->|"uses artifacts"| node_artifactmap
node_cdkpipeline -->|"uses factory"| node_buildfactory
node_corepipeline -.->|"specializes"| node_cdkpipeline
node_cdkpipeline -->|"creates pipeline"| node_pipeline
node_cdkpipeline -->|"packages artifacts"| node_cloudassembly
node_pipelineactions -->|"configures deployment"| node_cloudformation

click node_constructs "https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/core"
click node_stacks "https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/core"
click node_cdkapp "https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/core"
click node_serviceconstructs "https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib"
click node_rdsengines "https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-rds/lib/engine.ts"
click node_pipeline "https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-codepipeline/lib/pipeline.ts"
click node_pipelineactions "https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-codepipeline-actions/lib/cloudformation/pipeline-actions.ts"
click node_imagepipeline "https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/aws-imagebuilder-alpha/lib/image-pipeline.ts"
click node_redshiftquery "https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/aws-redshift-alpha/lib/private/database-query.ts"
click node_cloudassembly "https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/blueprint/file-set.ts"
click node_pipelinegraph "https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/helpers-internal/pipeline-graph.ts"
click node_cdkpipeline "https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts"
click node_artifactmap "https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/codepipeline/artifact-map.ts"
click node_buildfactory "https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/codepipeline/private/codebuild-factory.ts"
click node_corepipeline "https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/main/pipeline-base.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_constructs,node_stacks,node_cdkapp toneBlue
class node_serviceconstructs,node_rdsengines,node_pipeline,node_pipelineactions,node_imagepipeline,node_redshiftquery toneAmber
class node_cli,node_cloudassembly,node_cloudformation,node_deployedstack toneMint
class node_pipelinegraph,node_cdkpipeline,node_artifactmap,node_buildfactory,node_corepipeline toneRose
class node_developer toneIndigo
```

## Components

### Infrastructure authoring

- [Constructs](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/core): `packages/aws-cdk-lib/core`
- [Stacks](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/core): `packages/aws-cdk-lib/core`
- [CDK app](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib/core): `packages/aws-cdk-lib/core`

### AWS constructs

- [Service constructs](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk-lib): `packages/aws-cdk-lib`
- [RDS engines](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-rds/lib/engine.ts): `packages/aws-cdk-lib/aws-rds/lib/engine.ts`
- [CodePipeline](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-codepipeline/lib/pipeline.ts): `packages/aws-cdk-lib/aws-codepipeline/lib/pipeline.ts`
- [CloudFormation actions](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-codepipeline-actions/lib/cloudformation/pipeline-actions.ts): `packages/aws-cdk-lib/aws-codepipeline-actions/lib/cloudformation/pipeline-actions.ts`
- [Image Builder pipeline](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/aws-imagebuilder-alpha/lib/image-pipeline.ts): `packages/@aws-cdk/aws-imagebuilder-alpha/lib/image-pipeline.ts`
- [Redshift query](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/aws-redshift-alpha/lib/private/database-query.ts): `packages/@aws-cdk/aws-redshift-alpha/lib/private/database-query.ts`

### Synthesis and deployment

- **CDK CLI**
- [Cloud assembly](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/blueprint/file-set.ts): `packages/aws-cdk-lib/pipelines/lib/blueprint/file-set.ts`
- **CloudFormation**
- **Deployed stack**

### Pipeline internals

- [Pipeline graph](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/helpers-internal/pipeline-graph.ts): `packages/aws-cdk-lib/pipelines/lib/helpers-internal/pipeline-graph.ts`
- [CDK Pipelines](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts): `packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts`
- [Artifact mapping](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/codepipeline/artifact-map.ts): `packages/aws-cdk-lib/pipelines/lib/codepipeline/artifact-map.ts`
- [Build factory](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/codepipeline/private/codebuild-factory.ts): `packages/aws-cdk-lib/pipelines/lib/codepipeline/private/codebuild-factory.ts`
- [Pipeline base](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/pipelines/lib/main/pipeline-base.ts): `packages/aws-cdk-lib/pipelines/lib/main/pipeline-base.ts`

### Other components

- **Developer**

## Connections

- Developer → Constructs: defines (evidence: `README.md`)
- Constructs → Stacks: compose into (evidence: `README.md`)
- Stacks → CDK app: form (evidence: `README.md`)
- Developer → CDK CLI: interacts with (evidence: `README.md`)
- CDK CLI → CDK app: synthesizes (evidence: `README.md`)
- CDK CLI → CloudFormation: deploys through (evidence: `README.md`)
- CDK CLI → Deployed stack: diffs against (evidence: `README.md`)
- Constructs → Service constructs: use library (evidence: `README.md`)
- Service constructs → RDS engines: includes (evidence: `packages/aws-cdk-lib/aws-rds/lib/instance-engine.ts`)
- Service constructs → CodePipeline: includes (evidence: `packages/aws-cdk-lib/aws-codepipeline/lib/pipeline.ts`)
- Service constructs → Image Builder pipeline: includes
- Service constructs → Redshift query: includes
- CodePipeline → CloudFormation actions: accepts actions (evidence: `packages/aws-cdk-lib/aws-codepipeline/lib/pipeline.ts`)
- CDK Pipelines → Pipeline graph: translates graph (evidence: `packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts`)
- CDK Pipelines → Artifact mapping: uses artifacts (evidence: `packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts`)
- CDK Pipelines → Build factory: uses factory (evidence: `packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts`)
- Pipeline base → CDK Pipelines: specializes
- CDK Pipelines → CodePipeline: creates pipeline (evidence: `packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts`)
- CDK Pipelines → Cloud assembly: packages artifacts (evidence: `packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts`)
- CloudFormation actions → CloudFormation: configures deployment (evidence: `packages/aws-cdk-lib/aws-codepipeline-actions/lib/cloudformation/pipeline-actions.ts`)
