Recommended AWS CDK project structure for Python applications

The project implements a user management backend component that uses Amazon API Gateway, AWS Lambda and Amazon DynamoDB to provide basic CRUD operations for managing users. The project also includes a continuous deployment pipeline.

diagram * Diagram generated using

Create a new repository from aws-cdk-project-structure-python

This project is a template. Click “Use this template” (see the screenshot below) in the repository main page to create your own repository based on aws-samples/aws-cdk-project-structure-python. This is optional for deploying the component to the development environment, but required for deploying the pipeline.


The instructions below use the aws-cdk-project-structure-python repository.

Create development environment

See Getting Started With the AWS CDK for additional details and prerequisites

Clone the code

git clone
cd aws-cdk-project-structure-python

Create Python virtual environment and install the dependencies

python3.7 -m venv .venv
source .venv/bin/activate
# [Optional] Needed to upgrade dependencies and cleanup unused packages
pip install pip-tools==6.1.0

[Optional] Upgrade AWS CDK Toolkit version

Note: If you are planning to upgrade dependencies, first push the upgraded AWS CDK Toolkit version. See (pipelines): Fail synth if pinned CDK CLI version is older than CDK library version for more details.

vi package.json  # Update "aws-cdk" package version

[Optional] Upgrade dependencies (ordered by constraints)

Consider AWS CDK Toolkit (CLI) compatibility when upgrading AWS CDK packages version.

pip-compile --upgrade api/runtime/
pip-compile --upgrade
pip-compile --upgrade
# [Optional] Cleanup unused packages
pip-sync api/runtime/requirements.txt requirements.txt requirements-dev.txt

Deploy the component to development environment

The UserManagementBackend-Dev stage uses your default AWS account and region. It consists of two stacks – stateful (database) and stateless (API and monitoring)

npx cdk deploy "UserManagementBackend-Dev/*"

Example outputs for npx cdk deploy "UserManagementBackend-Dev/*":

 ✅  UserManagementBackendDevStateful7B33C11B (UserManagementBackend-Dev-Stateful)

UserManagementBackendDevStateful7B33C11B.ExportsOutputFnGetAttDatabaseTableF104A135ArnDAC15A6A = arn:aws:dynamodb:eu-west-1:111111111111:table/UserManagementBackend-Dev-Stateful-DatabaseTableF104A135-1LVXRPCPOKVZQ
UserManagementBackendDevStateful7B33C11B.ExportsOutputRefDatabaseTableF104A1356B7D7D8A = UserManagementBackend-Dev-Stateful-DatabaseTableF104A135-1LVXRPCPOKVZQ

 ✅  UserManagementBackendDevStateless0E5B7E4B (UserManagementBackend-Dev-Stateless)

UserManagementBackendDevStateless0E5B7E4B.APIHandlerArn = arn:aws:lambda:eu-west-1:111111111111:function:UserManagementBackend-Dev-Stateless-APIHandler-PJjw0Jn7Waq0
UserManagementBackendDevStateless0E5B7E4B.APIHandlerName = UserManagementBackend-Dev-Stateless-APIHandler-PJjw0Jn7Waq0
UserManagementBackendDevStateless0E5B7E4B.EndpointURL =
UserManagementBackendDevStateless0E5B7E4B.RestAPIId = zx5s6bum21

Deploy the pipeline


npx cdk deploy UserManagementBackend-Pipeline

Delete all stacks

Do not forget to delete the stacks to avoid unexpected charges

npx cdk destroy "UserManagementBackend-Dev/*"
npx cdk destroy UserManagementBackend-Pipeline
npx cdk destroy "UserManagementBackend-Pipeline/UserManagementBackend-Prod/*"

Delete the AWS CodeStar Connections connection if it is no longer needed. Follow the instructions in Delete a connection.

Testing the web API

Below are examples that show the available resources and how to use them:

endpoint_url=$(aws cloudformation describe-stacks \
  --stack-name UserManagementBackend-Dev-Stateless \
  --query 'Stacks[*].Outputs[?OutputKey==`EndpointURL`].OutputValue' \
  --output text)

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"username":"john", "email":"[email protected]"}' \

curl \
    -H "Content-Type: application/json" \
    -X GET \

curl \
    -H "Content-Type: application/json" \
    -X PUT \
    -d '{"country":"US", "state":"WA"}' \

curl \
    -H "Content-Type: application/json" \
    -X DELETE \


See CONTRIBUTING for more information.


This code is licensed under the MIT-0 License. See the LICENSE file.


GitHub - aws-samples/aws-cdk-project-structure-python: Recommended AWS CDK project structure for Python applications
Recommended AWS CDK project structure for Python applications - GitHub - aws-samples/aws-cdk-project-structure-python: Recommended AWS CDK project structure for Python applications