aws-lambda-handler-cookbook: a CDK blueprint for a production Lambda service

The questions it answers are infrastructure questions

The README states the problem plainly: starting a Serverless service can be overwhelming because you have to settle many questions that have nothing to do with your business domain. The list it gives runs from how to deploy to the cloud and which infrastructure as code framework to choose, through what a SaaS-oriented CI/CD pipeline must contain, how to handle observability, logging, tracing and metrics, how to write the Lambda function, how to handle testing, and finally what makes a handler resilient, traceable and easy to maintain.

The answer offered is a skeleton Python serverless service blueprint that implements best practices for AWS Lambda, serverless CI/CD and AWS CDK in one project. That is a narrower and more useful promise than a framework. You are not learning a new abstraction layer, you are looking at one engineer's set of answers and reusing the wiring.

The repository is also a template in the GitHub sense, but the README points out that you can start from a clean service without using the Template button, which is the more deliberate path.

The blueprint runs a real orders service, not a hello world

The service the blueprint deploys handles orders. It puts an API Gateway in front of Lambda integrations and stores data in a DynamoDB table, with four routes: `POST /api/orders/` creates an order, `GET /api/orders/{order_id}` reads one, `DELETE /api/orders/{order_id}` removes one, and `GET /api/orders/?limit={n}&next_token={cursor}` lists them with pagination, served by an AWS Lambda Managed Instances pool.

That last detail is the one to notice. Listing is the operation most likely to need predictable latency and predictable cost, and here it is separated from the write path and run on a capacity pool of EC2 instances across two availability zones, behind an alias named live. Create, get and delete stay on ordinary Lambda functions.

The service is also a worked example of the hard parts of a serverless API. Every `/api/orders` route requires an Amazon Cognito access token passed as `Authorization: Bearer <token>`, and the handler verifies the JWT against Cognito, while `/swagger` stays public so the API description can be read without credentials. A Lambda Layer carries the common dependencies shared by the functions, and a separate DynamoDB table provides idempotency for the create path.

The architecture covers WAF, AppConfig and token augmentation

The README includes a mermaid diagram of the deployed system, and the components in it describe the choices the blueprint makes. The client signs in against a Cognito User Pool with a group for managers, and a Pre Token Generation Lambda function adds the audience and scopes to the token before the API Gateway sees it. Behind the gateway sits a WAF WebACL with AWS Managed Rules. A second DynamoDB table holds idempotency records alongside the orders table, and AppConfig provides feature flags that the create handler reads.

Reading the diagram as a checklist is more useful than reading it as artwork. For a new service, the questions it answers are: where does token augmentation happen, what protects the edge, how do you avoid duplicate orders on a retried request, and how do you roll out a feature flag without a code deploy.

The routes are also split into separate Lambda functions rather than one function with a switch statement, and each function attaches to the shared layer. That is a choice about cold start and blast radius, and it is the kind of decision you inherit when you start from this repository.

Cookiecutter, uv and make deploy are the setup path

The documented route to a working copy is Cookiecutter, pointed at the author's separate template repository:

cookiecutter gh:ran-isenberg/cookiecutter-serverless-python

The README notes that Cookiecutter is installed with pip or with `brew install cookiecutter` or `pip install cookiecutter`, and that the questions asked during the run let you choose the repo name and service name. After the copy, the README says the developer environment is set and you are ready to deploy:

cd {new repo folder}
uv sync
make deploy

The dependency step is `uv`, and the README asks that you have uv installed. The repository root confirms the shape of the tooling: a `pyproject.toml` with a hatchling build backend, a `uv.lock`, a `Makefile` and a `Makefile_windows`, a `cdk/` directory holding the infrastructure code as a local editable package named service-cdk, and a `service/` directory for the handler code.

There is also a one-line route to a full check, since the README states that `make pr` runs all checks, synth, file formatters, unit tests, deploys to AWS and runs integration and end to end tests.

make pr is the whole quality loop in one target

The Makefile is the clearest evidence of what the blueprint thinks a serverless project needs. The `dev` target installs pre-commit and uv, installs the git hooks, syncs the environment and runs `npm ci`, which covers the Node side of the CDK tooling:

dev:
	pip install --upgrade pip pre-commit uv
	pre-commit install
	uv sync
	npm ci

Testing is split into four suites, each run with pytest and coverage over the service package:

unit:
	uv run pytest tests/unit  --cov-config=.coveragerc --cov=service --cov-report xml

integration:
	uv run pytest tests/integration  --cov-config=.coveragerc --cov=service --cov-report xml

e2e:
	uv run pytest tests/e2e  --cov-config=.coveragerc --cov=service --cov-report xml

The fourth is the infrastructure suite, which depends on a build step that assembles the Lambda bundle and the layer requirements. Alongside them the Makefile carries `lint` and `format` targets driven by ruff, a `mypy-lint` target over service, cdk and tests, a `complex` target that runs radon and xenon with maximum thresholds of A, a `deps` target that exports requirements files for the Lambda layer, and `docs`, `openapi` and `compare-openapi` targets for the API description. The `tests/` directory is correspondingly split into unit, infrastructure, integration and e2e.

The dependency set pins a current stack, including Python 3.14

The runtime requirement is stated in `pyproject.toml`:

requires-python = ">=3.14"

The runtime dependencies are what tell you the style of the code. `pydantic>=2.12.0` with `email-validator` covers validation, `aws-lambda-powertools[tracer,jwt]>=3.36.0` provides tracing and JWT verification, `pydynox[pydantic]>=0.22.0` is the dependency injection container, `cachetools` and `boto3>=1.26.125` handle caching and AWS calls, and `aws-lambda-env-modeler` is used to type environment variables rather than reading them as loose strings.

The infrastructure side is pinned too. The Node package.json holds `aws-cdk` at `2.1145.0` and `cdk` at `^2.1129.0`, while the Python side requires `aws-cdk-lib>=2.250.0` with `constructs>=10.0.0`, `cdk-nag>=3.0.0,<4.0.0`, the alpha constructs for Lambda Python and EC2, and `cdk-monitoring-constructs` for dashboards. The presence of cdk-nag and the monitoring constructs says as much about the intended audience as any line of prose: people who intend to pass security checks and who expect dashboards to exist from day one.

On the AWS side the README also carries a badge for the OpenSSF Scorecard and a codecov badge, and the root has a `.pre-commit-config.yaml`, a `.markdownlint.yaml` and a `mypy.ini`.

Version 11.0.1 landed on the same day as the last push

The release history is dense and recent. v11.0.0, v11.0 and v11.0.1 were all published on 2026-10-18, and the last push was on 2026-10-18 as well, with the project version in `pyproject.toml` reading:

version = "11.0"

The repository is not archived, and the pace suggests a project in active rotation rather than a stable library. The `aidlc-docs/` directory, the `CLAUDE.md` file, the `llms.txt` file and the `.claude/` directory at the root indicate that AI-assisted development artifacts are part of the repository now, which is a signal about how the blueprint is maintained as much as about its tooling.

The licence is MIT, declared in the classifiers as MIT License with the LICENSE file at the root, though the `pyproject.toml` metadata field carries the text MIT-0. Those two identifiers are not the same thing, and the LICENSE file is the one that governs. For a repository meant to be copied into your own codebase, reading that file before you copy anything is the sensible step.

The alternative is the Powertools layer on its own

The project names its own inspiration. The README records that the author spoke at AWS re:Invent 2023 with Heitor Lessa, former Chief Architect of Powertools for AWS Lambda, about the concepts implemented here, and Powertools for AWS Lambda is a runtime dependency of the blueprint, pulled in with the tracer and jwt extras.

That relationship defines the real alternative. Powertools for AWS Lambda on its own is a utility layer for tracing, metrics, logging and JWT handling, and it leaves every infrastructure question open: how the service is deployed, how the pipeline is written, how the API is shaped, how the data layer is modelled. This repository answers all of those, and in exchange you take a fixed set of answers that you have to unpick if they do not match your needs. A team that has already solved deployment and pipeline questions can adopt Powertools alone and keep its own structure.

There is a second comparison worth making, at the level of the whole category. The README notes that the repository was recommended in an AWS blog post about best practices for accelerating development with serverless blueprints. That framing puts it among other blueprints rather than above them, and the deciding factor between this one and another blueprint is rarely the code, which is mostly the same Lambda and CDK patterns, and more often how close the data model, the auth scheme and the pipeline come to what you already have.

Editorial conclusion

This blueprint fits a team that wants a working serverless service skeleton in Python, with API Gateway, DynamoDB, Cognito, CDK and a pipeline already wired, and that is prepared to edit rather than reuse it. It does not fit a team whose runtime is not Python 3.14, whose traffic does not need Cognito-protected API routes, or who wants a thin library instead of a full service layout. Verify first that the Cookiecutter template and this repository are in step, that the AWS CDK version pinned in package.json still synthesises against your account, and which of the pinned dependencies, Powertools and pydynox in particular, you are prepared to keep.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. ran-isenberg/aws-lambda-handler-cookbook on GitHub
4. README
5. Releases