# ran-isenberg/aws-lambda-handler-cookbook architecture

> Architecture diagram of the GitHub repository ran-isenberg/aws-lambda-handler-cookbook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ran-isenberg/aws-lambda-handler-cookbook
- Repository: https://github.com/ran-isenberg/aws-lambda-handler-cookbook

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client"]:::external

    %% AWS Resources
    subgraph "AWS Resources"
        direction TB
        APIGW["API Gateway"]:::aws
        WAF["WAF"]:::aws
        LambdaFunc["Lambda Function"]:::aws
        DynamoDB["DynamoDB"]:::data
        AppConfigRes["AppConfig"]:::config
        CloudWatch["CloudWatch Logs/Metrics/X-Ray"]:::observ
    end

    %% Infrastructure (CDK Constructs)
    subgraph "Infrastructure (CDK Constructs)"
        direction TB
        APIConstruct["api_construct"]:::infra
        DBConstruct["api_db_construct"]:::infra
        ConfigConstruct["configuration_construct"]:::infra
        Schema["schema"]:::infra
        DevConfigJSON["dev_configuration.json"]:::infra
        WAFConstruct["waf_construct"]:::infra
        MonitoringConstruct["monitoring"]:::infra
        ServiceStack["service_stack"]:::infra
        CDKUtils["utils"]:::infra
    end

    %% Service Code
    subgraph "Service Code"
        direction TB
        subgraph "Handler Layer"
            direction TB
            AppEntry["app.py"]:::code
            HandleCreate["handle_create_order.py"]:::code
            subgraph "Handler Models"
                direction TB
                EnvVars["env_vars.py"]:::code
                DynConfigModel["dynamic_configuration.py"]:::code
            end
            subgraph "Handler Utilities"
                direction TB
                ObsUtil["observability.py"]:::code
                DynConfigUtil["dynamic_configuration.py"]:::code
                APIResolver["rest_api_resolver.py"]:::code
            end
        end
        subgraph "Logic Layer"
            direction TB
            CreateOrderLogic["create_order.py"]:::code
            IdempotencyUtil["idempotency.py"]:::code
        end
        subgraph "Data Access Layer"
            direction TB
            DynamoDAL["dynamo_dal_handler.py"]:::code
            DBHandler["db_handler.py"]:::code
            subgraph "DAL Models"
                direction TB
                DBModels["db.py"]:::code
            end
        end
        subgraph "Service Models"
            direction TB
            InputModel["input.py"]:::code
            OutputModel["output.py"]:::code
            OrderModel["order.py"]:::code
            ExceptionsModel["exceptions.py"]:::code
        end
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        PRWorkflow["pr-serverless-service.yml"]:::pipeline
        MainWorkflow["main-serverless-service.yml"]:::pipeline
        MakefileNode["Makefile"]:::pipeline
        OpenAPIGen["generate_openapi.py"]:::pipeline
    end

    %% Connections: Client to API
    Client -->|"POST /api/orders"| APIGW
    APIGW -->|invokes| WAF
    WAF -->|forwards| LambdaFunc

    %% Lambda to service code
    LambdaFunc -->|entrypoint| AppEntry
    AppEntry -->|calls| HandleCreate
    HandleCreate -->|uses| EnvVars
    HandleCreate -->|uses| DynConfigModel
    HandleCreate -->|calls| CreateOrderLogic
    HandleCreate -->|uses| ObsUtil
    HandleCreate -->|uses| DynConfigUtil
    HandleCreate -->|uses| APIResolver

    %% Logic to DAL
    CreateOrderLogic -->|calls| DynamoDAL
    CreateOrderLogic -->|uses| IdempotencyUtil
    DynamoDAL -->|implements| DBHandler
    DBHandler -->|models| DBModels

    %% Models used
    HandleCreate -->|"validates"| InputModel
    HandleCreate -->|"returns"| OutputModel
    CreateOrderLogic -->|"uses"| OrderModel
    CreateOrderLogic -->|"raises"| ExceptionsModel

    %% Lambda to AWS Resources
    LambdaFunc -->|PutItem/GetItem| DynamoDB
    LambdaFunc -->|GetConfiguration| AppConfigRes
    LambdaFunc -->|logs/metrics/traces| CloudWatch

    %% CDK deploys AWS resources
    ServiceStack --> APIGW
    ServiceStack --> WAF
    ServiceStack --> DynamoDB
    ServiceStack --> AppConfigRes
    ServiceStack --> CloudWatch
    APIConstruct --> ServiceStack
    DBConstruct --> ServiceStack
    ConfigConstruct --> ServiceStack
    Schema --> ConfigConstruct
    DevConfigJSON --> ConfigConstruct
    WAFConstruct --> ServiceStack
    MonitoringConstruct --> ServiceStack
    CDKUtils --> ServiceStack

    %% Pipeline to CDK
    PRWorkflow -->|CI| ServiceStack
    MainWorkflow -->|Deploy| ServiceStack
    MakefileNode -->|commands| ServiceStack
    OpenAPIGen -->|generates| APIConstruct

    %% Styles
    classDef aws fill:#aed6f1,stroke:#1f78b4,color:#000
    classDef infra fill:#d0e6f5,stroke:#1c75bc,color:#000
    classDef code fill:#d5f5d5,stroke:#239a3b,color:#000
    classDef data fill:#f9e79f,stroke:#e67e22,color:#000
    classDef config fill:#f0f0f0,stroke:#7f8c8d,color:#000
    classDef pipeline fill:#e8daef,stroke:#8e44ad,color:#000
    classDef observ fill:#f9e79f,stroke:#e74c3c,color:#000
    classDef external fill:#ffffff,stroke:#7f8c8d,color:#000

    %% Click Events
    click APIConstruct "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/cdk/service/api_construct.py"
    click DBConstruct "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/cdk/service/api_db_construct.py"
    click ConfigConstruct "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/cdk/service/configuration/configuration_construct.py"
    click Schema "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/cdk/service/configuration/schema.py"
    click DevConfigJSON "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/cdk/service/configuration/json/dev_configuration.json"
    click WAFConstruct "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/cdk/service/waf_construct.py"
    click MonitoringConstruct "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/cdk/service/monitoring.py"
    click ServiceStack "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/cdk/service/service_stack.py"
    click CDKUtils "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/cdk/service/utils.py"
    click AppEntry "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/app.py"
    click HandleCreate "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/handlers/handle_create_order.py"
    click EnvVars "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/handlers/models/env_vars.py"
    click DynConfigModel "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/handlers/models/dynamic_configuration.py"
    click ObsUtil "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/handlers/utils/observability.py"
    click DynConfigUtil "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/handlers/utils/dynamic_configuration.py"
    click APIResolver "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/handlers/utils/rest_api_resolver.py"
    click CreateOrderLogic "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/logic/create_order.py"
    click IdempotencyUtil "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/logic/utils/idempotency.py"
    click DynamoDAL "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/dal/dynamo_dal_handler.py"
    click DBHandler "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/dal/db_handler.py"
    click DBModels "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/dal/models/db.py"
    click InputModel "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/models/input.py"
    click OutputModel "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/models/output.py"
    click OrderModel "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/models/order.py"
    click ExceptionsModel "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/service/models/exceptions.py"
    click PRWorkflow "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/.github/workflows/pr-serverless-service.yml"
    click MainWorkflow "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/.github/workflows/main-serverless-service.yml"
    click MakefileNode "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/tree/main/Makefile"
    click OpenAPIGen "https://github.com/ran-isenberg/aws-lambda-handler-cookbook/blob/main/generate_openapi.py"
```
