How ran-isenberg/aws-lambda-handler-cookbook works
Project Type and Purpose
• This is a Serverless Python “blueprint” repository for building AWS Lambda–based microservices.
• It provides:
• AWS CDK IaC to define and deploy the service (API Gateway, Lambda, DynamoDB, WAF, AppConfig, CloudWatch dashboards/alarms).
• A three-layer Lambda code skeleton (handler, business logic, data access) following AWS Powertools best practices.
• A full GitHub Actions–based CI/CD pipeline with security, infrastructure, integration, and E2E tests.
• The sample service implements an “orders” API (POST /api/orders) that writes to DynamoDB, uses AppConfig for feature flags and dynamic configuration, and is protected by WAF.
Main Components
a. Infrastructure (cdk/service/)
– api_construct: defines API Gateway, Lambda integration, and Swagger endpoint
– api_db_construct: DynamoDB table definition and permissions
– configuration_construct: AppConfig resource, configuration schemas
– waf_construct: WAF web ACL attaching managed rules to API Gateway
– service_stack: assembles all constructs into one CDK stack
b. Service Code (service/)
– handler layer (app.py, service/handlers): API handler entry point, request parsing
– logic layer (service/logic): core “create_order” business rules, idempotency, validation
– data access layer (service/dal): DynamoDB operations via powertools, models
– models (service/models): Pydantic request/response schemas and exceptions
– utilities (observability, dynamic config, env vars) leveraging AWS Powertools
c. Deployment & Pipeline
– GitHub Actions workflows (.github/workflows): PR checks, main deploy to dev/stage/prod
– Makefile for local commands (make deploy, make pr)
– generate_openapi.py: regenerates swagger JSON used in CDK and docs
d. Observability & Monitoring
– CloudWatch Dashboards and Alarms (constructed in monitoring.py)
– Tracing and Metrics via AWS Lambda Powertools libraries
Relationships & Data Flows
• Client → API Gateway → WAF → Lambda Handler
• Handler uses Powertools middleware for logging, tracing, metrics
• Lambda Handler → Business Logic → Data Access Layer → DynamoDB
• Lambda Handler → AWS AppConfig (via AppConfig client) for dynamic config & feature flags
• Lambda logs, metrics, and traces → CloudWatch Logs, Metrics, X-Ray
• CDK Pipeline → Deploys Cloud Resources → Triggers Integration/E2E tests against the deployed API
• GitHub Actions → Lints, Unit Tests, CDK Synth, Security Scans, Deploy, Integration/E2E
Architectural Patterns and Principles
• Three-layer Lambda architecture: Handler / Logic / DAL
• Infrastructure as Code (AWS CDK) with modular “constructs” (API, DB, Config, WAF, Monitoring)
• Feature flags and dynamic configuration using AWS AppConfig
• Idempotent API design via idempotency utilities
• Observability best practices: structured logging, metrics, tracing, dashboard/alarms
• CI/CD as Code: GitHub Actions enforcing tests, security, and multi-environment deployments