# awslabs/aws-lambda-go-api-proxy architecture

> Architecture diagram of the GitHub repository awslabs/aws-lambda-go-api-proxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awslabs/aws-lambda-go-api-proxy
- Repository: https://github.com/awslabs/aws-lambda-go-api-proxy

## Overview

##### Project type and purpose
- This is an open-source Go library (“aws-lambda-go-api-proxy”) that provides adapter layers to run Go HTTP frameworks (Gin, Fiber, Chi, Echo, GorillaMux, Negroni, plain http.HandlerFunc) as AWS Lambda functions behind API Gateway.

##### File structure
- Top-level:
- core/         ← central converter logic
- [framework]/  ← one directory per supported framework (gin/, fiber/, echo/, chi/, gorillamux/, negroni/, handlerfunc/, httpadapter/)
- examples/     ← full examples (e.g., fiber)
- sample/       ← deployable SAM application
- Makefile, CI configs, README, LICENSE, etc.
- core/ contains request.go, response.go, types.go, plus ALB and v2 variants: implements RequestAccessor → ProxyEventToHTTPRequest() and ProxyResponseWriter → GetProxyResponse().
- Each framework dir contains an adapter.go implementing the adapter type (e.g., GinLambda) by embedding core.RequestAccessor and wiring up the framework’s engine.
- sample/ holds a CloudFormation/SAM template and a Go main.go showing how to wire up one adapter into a real Lambda function.

##### Key insights from README
- Shows call flow: API Gateway → Lambda handler → adapter.ProxyWithContext → core.ProxyEventToHTTPRequest → framework ServeHTTP → core.ProxyResponseWriter → API Gateway response.
- Emphasizes the Adapter Pattern: each framework adapter uses the same core interfaces and conversion logic.
- Explains supported Lambda payload variants (ALB events, v2 payloads, etc).

##### Main components
a. AWS API Gateway
b. AWS Lambda Runtime
c. Adapter Layer (per framework):
- HTTPAdapter (stdlib)
- GinLambda
- FiberLambda
- ChiLambda, etc.
d. Core Conversion Module
- RequestAccessor (ProxyEventToHTTPRequest)
- ProxyResponseWriter (GetProxyResponse)
e. Underlying Go HTTP Framework (Gin Engine, Fiber App, etc.)
f. User’s HTTP Handlers (business logic in Gin routes, Fiber handlers, etc.)
g. AWS CloudWatch Logs (optional)
h. Sample SAM Deployment (CloudFormation)

##### Relationships and interactions
1. API Gateway forwards incoming HTTP request as `APIGatewayProxyRequest` →
2. Lambda Runtime invokes Handler (generated by adapter).
3. Adapter receives (`ctx`, `APIGatewayProxyRequest`) → calls core.RequestAccessor.ProxyEventToHTTPRequest → produces `http.Request`.
4. Adapter creates core.ProxyResponseWriter, then calls frameworkEngine.ServeHTTP(responseWriter, request).
5. FrameworkEngine dispatches to user-defined HTTP routes/handlers → writes to responseWriter.
6. After ServeHTTP returns, adapter calls responseWriter.GetProxyResponse() → `APIGatewayProxyResponse`.
7. Lambda returns that to API Gateway → client receives HTTP response.
8. Throughout, logs flow to CloudWatch.

##### Architectural patterns and design principles
- Adapter Pattern: each framework adapter implements the same interface by embedding core conversion logic.
- Single Responsibility: core only handles event ↔ HTTP conversion; adapters only hook up frameworks.
- Layered design: AWS infra → Lambda runtime → adapter → core → framework → user code.

##### Technologies, frameworks, libraries
- Go standard library (net/http)
- AWS Lambda Go SDK (`github.com/aws/aws-lambda-go/events`, `lambda`)
- Core module (in-repo)
- Supported frameworks: Gin, Fiber, Echo, Chi, GorillaMux, Negroni, HandlerFunc
- AWS SAM (sample/sam.yaml)
- CloudFormation, AWS CLI for deployment

##### Elements
- Clear labels: “API Gateway”, “Lambda Runtime Handler”, “Core: RequestAccessor”, “Core: ProxyResponseWriter”, “Gin Engine”, “User Handler”, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% AWS Layer
    subgraph "AWS Layer"
        direction TB
        APIGW("API Gateway"):::aws
        LambdaRuntime("Lambda Runtime Handler"):::aws
        CloudWatch("CloudWatch Logs"):::aws
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        direction TB
        GinAdapter("GinLambda Adapter"):::adapter
        FiberAdapter("FiberLambda Adapter"):::adapter
        ChiAdapter("ChiLambda Adapter"):::adapter
        EchoAdapter("EchoLambda Adapter"):::adapter
        GorillaAdapter("GorillaMux Adapter"):::adapter
        NegroniAdapter("Negroni Adapter"):::adapter
        HandlerFuncAdapter("HandlerFunc Adapter"):::adapter
        HTTPStdAdapter("HTTPAdapter (stdlib)"):::adapter
    end

    %% Core Conversion Layer
    subgraph "Core Conversion Layer"
        direction TB
        RequestAccessor("Core: RequestAccessor"):::core
        ProxyResponseWriter("Core: ProxyResponseWriter"):::core
        SharedTypes("Core: Shared Types"):::core
    end

    %% Framework Layer
    subgraph "Framework Layer"
        direction TB
        GinEngine("Gin Engine"):::framework
        FiberApp("Fiber App"):::framework
        EchoEngine("Echo Engine"):::framework
        ChiRouter("Chi Router"):::framework
        GorillaMuxRouter("GorillaMux Router"):::framework
        NegroniEngine("Negroni"):::framework
        StdHandlerAdapter("Std HTTP Handler"):::framework
    end

    %% User Code Layer
    subgraph "User Code Layer"
        direction TB
        UserHandler("User HTTP Handlers"):::user
    end

    %% Sample SAM Deployment
    subgraph "Sample SAM Deployment"
        direction TB
        SAMTemplate("sam.yaml"):::sample
        SampleMain("main.go"):::sample
        SamplePets("pets.go"):::sample
    end

    %% Flow connections
    APIGW -->|"APIGatewayProxyRequest"| LambdaRuntime
    LambdaRuntime -->|"invoke Handler"| GinAdapter
    LambdaRuntime -->|"invoke Handler"| FiberAdapter
    LambdaRuntime -->|"invoke Handler"| ChiAdapter
    LambdaRuntime -->|"invoke Handler"| EchoAdapter
    LambdaRuntime -->|"invoke Handler"| GorillaAdapter
    LambdaRuntime -->|"invoke Handler"| NegroniAdapter
    LambdaRuntime -->|"invoke Handler"| HandlerFuncAdapter
    LambdaRuntime -->|"invoke Handler"| HTTPStdAdapter

    %% Adapter to Core
    GinAdapter -->|"ProxyEventToHTTPRequest"| RequestAccessor
    FiberAdapter -->|"ProxyEventToHTTPRequest"| RequestAccessor
    ChiAdapter -->|"ProxyEventToHTTPRequest"| RequestAccessor
    EchoAdapter -->|"ProxyEventToHTTPRequest"| RequestAccessor
    GorillaAdapter -->|"ProxyEventToHTTPRequest"| RequestAccessor
    NegroniAdapter -->|"ProxyEventToHTTPRequest"| RequestAccessor
    HandlerFuncAdapter -->|"ProxyEventToHTTPRequest"| RequestAccessor
    HTTPStdAdapter -->|"ProxyEventToHTTPRequest"| RequestAccessor

    %% Core to Framework
    RequestAccessor -->|"http.Request"| GinEngine
    RequestAccessor -->|"http.Request"| FiberApp
    RequestAccessor -->|"http.Request"| EchoEngine
    RequestAccessor -->|"http.Request"| ChiRouter
    RequestAccessor -->|"http.Request"| GorillaMuxRouter
    RequestAccessor -->|"http.Request"| NegroniEngine
    RequestAccessor -->|"http.Request"| StdHandlerAdapter

    %% Framework to User Code
    GinEngine -->|"ServeHTTP"| UserHandler
    FiberApp -->|"ServeHTTP"| UserHandler
    EchoEngine -->|"ServeHTTP"| UserHandler
    ChiRouter -->|"ServeHTTP"| UserHandler
    GorillaMuxRouter -->|"ServeHTTP"| UserHandler
    NegroniEngine -->|"ServeHTTP"| UserHandler
    StdHandlerAdapter -->|"ServeHTTP"| UserHandler

    %% User back to Core
    UserHandler -->|"write Response"| ProxyResponseWriter

    %% Core back to Lambda & API GW
    ProxyResponseWriter -->|"APIGatewayProxyResponse"| LambdaRuntime
    LambdaRuntime -->|"APIGatewayProxyResponse"| APIGW

    %% Logging
    APIGW ---|logs| CloudWatch
    LambdaRuntime ---|logs| CloudWatch
    RequestAccessor ---|logs| CloudWatch
    ProxyResponseWriter ---|logs| CloudWatch
    GinEngine ---|logs| CloudWatch
    FiberApp ---|logs| CloudWatch
    UserHandler ---|logs| CloudWatch

    %% Sample SAM flow
    SAMTemplate -->|deploys| LambdaRuntime
    SampleMain -->|wires adapter| GinAdapter
    SamplePets -->|defines routes| UserHandler

    %% Click Events
    click GinAdapter "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/gin/adapter.go"
    click FiberAdapter "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/fiber/adapter.go"
    click ChiAdapter "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/chi/adapter.go"
    click EchoAdapter "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/echo/adapter.go"
    click GorillaAdapter "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/gorillamux/adapter.go"
    click NegroniAdapter "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/negroni/adapter.go"
    click HandlerFuncAdapter "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/handlerfunc/adapter.go"
    click HTTPStdAdapter "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/httpadapter/adapter.go"
    click RequestAccessor "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/core/request.go"
    click ProxyResponseWriter "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/core/response.go"
    click SharedTypes "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/core/types.go"
    click SAMTemplate "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/sample/sam.yaml"
    click SampleMain "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/sample/main.go"
    click SamplePets "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/sample/pets.go"
    click FiberApp "https://github.com/awslabs/aws-lambda-go-api-proxy/blob/master/examples/fiber/main.go"

    %% Classes
    classDef aws fill:#FFA500,stroke:#333,stroke-width:1px
    classDef adapter fill:#1f77b4,stroke:#333,stroke-width:1px
    classDef core fill:#1f77b4,stroke:#333,stroke-width:1px
    classDef framework fill:#2ca02c,stroke:#333,stroke-width:1px
    classDef user fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef sample fill:#9467bd,stroke:#333,stroke-width:1px
```
