# parameshg/stateful-serverless-api architecture

> Architecture diagram of the GitHub repository parameshg/stateful-serverless-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parameshg/stateful-serverless-api
- Repository: https://github.com/parameshg/stateful-serverless-api

## Overview

##### Project Type and Purpose
- This project is an ASP.NET Core Web API that is designed to run as an AWS Lambda function. It leverages the Amazon.Lambda.AspNetCoreServer NuGet package to bridge API requests (via API Gateway or an Application Load Balancer) into the ASP.NET Core framework.
- The application supports both cloud-based serverless execution and local development (using Kestrel), and it can be packaged as a Docker container.

##### Main Components
- AWS Components:
– API Gateway / Application Load Balancer: These serve as the entry point for HTTP requests when deployed.
– AWS Lambda: Represented by the LambdaEntryPoint class which bootstraps the ASP.NET Core hosting framework for serverless execution.
– Serverless Resources: Indicated by the serverless.tf file (Terraform scripts that declare the necessary AWS resources).
- ASP.NET Core Components:
– LambdaEntryPoint.cs: Acts as the Lambda adapter deriving from APIGatewayProxyFunction (or the variation for ALB), initiating the ASP.NET Core pipeline.
– LocalEntryPoint.cs: Provides a Main() for local execution using Kestrel.
– Startup.cs: The typical startup configuration that registers middleware, services, routing, etc.
- Controllers: Such as HomeController, IntegerController, and TestController—handle API endpoints.
- Domain & Business Logic:
– Domain (e.g., Ticker.cs) represents the core business entities.
– Handlers (e.g., CreateCounterHandler, IncrementCounterHandler, etc.) encapsulate the business logic for processing requests.
– Pipelines & Middlewares: These include ValidationMiddleware, IdentityMiddleware, and ValidationBehavior which help in pre-processing requests and enforcing policies.
- Data Access:
– Repositories: Components like DynamoRepository, NullRepository, and extensions (DynamoExtensions) that abstract data access operations.
- Request Models: Under the Requests folder there are request classes (CreateRequest, IncrementRequest, etc.) representing the data contract for incoming API calls.

##### Relationships and Interactions
- That requests are forwarded to AWS Lambda (LambdaEntryPoint) which then:
– Bootstraps the ASP.NET Core pipeline (via Startup.cs).
– Passes through configured middleware (IdentityMiddleware, ValidationMiddleware).
– Routes to appropriate controllers (HomeController, etc.).
– Invokes corresponding Handler classes which process business logic.
– Interacts with the Repository layer to persist or retrieve data.
- That for local development the LocalEntryPoint.cs is used, running the service on Kestrel.
- Deployment considerations such as packaging as a Docker image, noting that Dockerfile handles either host-based builds or multi-stage builds.

##### Architectural Patterns and Design Principles
- Serverless Architecture: Emphasize the design for AWS Lambda and API Gateway integration.
- Separation of Concerns: Clear division between API (Controllers) and business logic (Handlers), with middleware handling cross-cutting concerns.
- Dependency Injection: Standard practice in ASP.NET Core for injecting services and repositories.
- Environment-Specific Configurations: Illustrate how different entry points (LambdaEntryPoint vs. LocalEntryPoint) support distinct deployment environments.

##### Final Checklist
- Maintain clarity by breaking the system into well-defined components.
- Notable code-level components like Handlers, Middleware, and Repositories that represent the business processing logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "AWS Components"
        AG["API Gateway/ALB"]:::aws
        LAMBDA["LambdaEntryPoint"]:::aws
        TERRAFORM["Serverless Resources"]:::aws
    end

    subgraph "Local Environment"
        LOCAL["LocalEntryPoint"]:::local
    end

    subgraph "ASP.NET Core Application"
        STARTUP["Startup.cs"]:::aspnet

        subgraph "Middleware"
            IDENTITY["IdentityMiddleware"]:::middleware
            VALIDATION["ValidationMiddleware"]:::middleware
            VALIDATIONBEHAVIOR["ValidationBehavior"]:::middleware
        end

        subgraph "Controllers"
            HOME["HomeController"]:::controller
            INTEGER["IntegerController"]:::controller
            TEST["TestController"]:::controller
        end

        subgraph "Business Logic (Handlers)"
            CREATE["CreateCounterHandler"]:::handler
            INCREMENT["IncrementCounterHandler"]:::handler
            DECREMENT["DecrementCounterHandler"]:::handler
            DELETE["DeleteCounterHandler"]:::handler
            GET["GetCounterHandler"]:::handler
            UPDATE["UpdateCounterHandler"]:::handler
        end

        subgraph "Domain & Data"
            TICKER["Ticker"]:::domain
            subgraph "Repositories"
                DYNAMO["DynamoRepository"]:::repo
                NULL["NullRepository"]:::repo
                DYNAMOEXT["DynamoExtensions"]:::repo
            end
            REQUESTS["Requests"]:::request
        end
    end

    %% Relationships
    AG -->|"forwards"| LAMBDA
    LAMBDA -->|"bootstraps"| STARTUP
    LOCAL -->|"bootstraps"| STARTUP
    TERRAFORM -->|"manages"| LAMBDA

    STARTUP -->|"configures"| IDENTITY
    STARTUP -->|"configures"| VALIDATION
    STARTUP -->|"configures"| VALIDATIONBEHAVIOR

    IDENTITY -->|"applies"| HOME
    VALIDATION -->|"applies"| HOME
    VALIDATIONBEHAVIOR -->|"validates"| HOME

    HOME -->|"routes"| CREATE
    HOME -->|"routes"| INCREMENT
    HOME -->|"routes"| DECREMENT
    HOME -->|"routes"| DELETE
    HOME -->|"routes"| GET
    HOME -->|"routes"| UPDATE

    INTEGER -->|"routes"| CREATE
    INTEGER -->|"routes"| INCREMENT
    INTEGER -->|"routes"| DECREMENT
    INTEGER -->|"routes"| DELETE
    INTEGER -->|"routes"| GET
    INTEGER -->|"routes"| UPDATE

    TEST -->|"routes"| CREATE
    TEST -->|"routes"| INCREMENT
    TEST -->|"routes"| DECREMENT
    TEST -->|"routes"| DELETE
    TEST -->|"routes"| GET
    TEST -->|"routes"| UPDATE

    CREATE -->|"uses"| DYNAMO
    INCREMENT -->|"uses"| DYNAMO
    DECREMENT -->|"uses"| NULL
    DELETE -->|"uses"| DYNAMOEXT
    GET -->|"uses"| DYNAMO
    UPDATE -->|"uses"| DYNAMO

    CREATE -->|"operates_on"| TICKER
    INCREMENT -->|"operates_on"| TICKER
    DECREMENT -->|"operates_on"| TICKER
    DELETE -->|"operates_on"| TICKER
    GET -->|"operates_on"| TICKER
    UPDATE -->|"operates_on"| TICKER

    CREATE -->|"consumes"| REQUESTS
    INCREMENT -->|"consumes"| REQUESTS
    DECREMENT -->|"consumes"| REQUESTS
    DELETE -->|"consumes"| REQUESTS
    GET -->|"consumes"| REQUESTS
    UPDATE -->|"consumes"| REQUESTS

    %% Click Events
    click LAMBDA "https://github.com/parameshg/stateful-serverless-api/blob/master/source/LambdaEntryPoint.cs"
    click LOCAL "https://github.com/parameshg/stateful-serverless-api/blob/master/source/LocalEntryPoint.cs"
    click TERRAFORM "https://github.com/parameshg/stateful-serverless-api/blob/master/serverless.tf"
    click STARTUP "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Startup.cs"
    click HOME "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Controllers/HomeController.cs"
    click INTEGER "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Controllers/IntegerController.cs"
    click TEST "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Controllers/TestController.cs"
    click TICKER "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Domain/Ticker.cs"
    click CREATE "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Handlers/CreateCounterHandler.cs"
    click INCREMENT "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Handlers/IncrementCounterHandler.cs"
    click DECREMENT "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Handlers/DecrementCounterHandler.cs"
    click DELETE "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Handlers/DeleteCounterHandler.cs"
    click GET "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Handlers/GetCounterHandler.cs"
    click UPDATE "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Handlers/UpdateCounterHandler.cs"
    click IDENTITY "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Middlewares/IdentityMiddleware.cs"
    click VALIDATION "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Middlewares/ValidationMiddleware.cs"
    click VALIDATIONBEHAVIOR "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Pipelines/ValidationBehavior.cs"
    click DYNAMO "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Repositories/DynamoRepository.cs"
    click NULL "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Repositories/NullRepository.cs"
    click DYNAMOEXT "https://github.com/parameshg/stateful-serverless-api/blob/master/source/Repositories/DynamoExtensions.cs"
    click REQUESTS "https://github.com/parameshg/stateful-serverless-api/tree/master/source/Requests"

    %% Styles
    classDef aws fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef local fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef aspnet fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef middleware fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef controller fill:#ccffff,stroke:#333,stroke-width:2px;
    classDef handler fill:#e5ccff,stroke:#333,stroke-width:2px;
    classDef repo fill:#ffe5cc,stroke:#333,stroke-width:2px;
    classDef domain fill:#d5e8d4,stroke:#333,stroke-width:2px;
    classDef request fill:#fff2cc,stroke:#333,stroke-width:2px;
```
