# rails-lambda/lamby architecture

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

- Interactive diagram: https://gitdiagram.com/rails-lambda/lamby
- Repository: https://github.com/rails-lambda/lamby

## Overview

##### Project type and purpose
- This is an open-source Ruby gem (“lamby”) that serves as an AWS Lambda Web Adapter for Rack-based applications (most commonly Rails).
- Its goal is to let you run a Rack (e.g., Rails) application on AWS Lambda behind Function URLs, API Gateway (HTTP/REST), or an Application Load Balancer.

##### File structure
- Top-level gem files: lamby.gemspec, Gemfile, Rakefile, LICENSE, README, .github workflows
- Bin scripts: bootstrap, console, setup, test, update – these drive development and testing tasks.
- lib/lamby/: core code – handler, Rack adapter layers (rack_http, rack_rest, rack_alb), proxy context/server, cold start metrics, debug, logger, config, and SSM parameter store integration.
- test/: unit tests and a dummy Rails app under test/dummy_app to simulate actual Rails behavior.

##### README for insights
- Describes support for multiple AWS invocation methods (Function URLs, API Gateway v1/v2, ALB).
- Points to “anatomy” docs that likely show internal flow: AWS event → Lamby handler → Rack → Rails.

##### Detailed callouts
- Cold start detection and metric emission in the handler.
- Bundle loading at cold start vs reuse on warm invocations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% AWS Layer
    subgraph "AWS Layer"
        direction TB
        FG["Function URL"]:::aws
        AG1["API Gateway v1"]:::aws
        AG2["API Gateway v2"]:::aws
        ALB["Application Load Balancer"]:::aws
        SSM_AWS["SSM Parameter Store"]:::aws
        CW["CloudWatch Logs & Metrics"]:::aws
    end

    %% Lambda Runtime
    subgraph "Lambda Runtime"
        direction TB
        Handler["Lamby::Handler"]:::lamby
        ProxyCtx["Lamby::ProxyContext"]:::lamby
        ProxySrv["Lamby::ProxyServer"]:::lamby
        AdapterHTTP["Rack HTTP Adapter"]:::lamby
        AdapterREST["Rack REST Adapter"]:::lamby
        AdapterALB["Rack ALB Adapter"]:::lamby
        ColdMetrics["Cold Start Metrics"]:::lamby
        Logger["Lamby::Logger"]:::lamby
        Debug["Lamby::Debug"]:::lamby
        Config["Lamby::Config"]:::lamby
        SSMInt["Lamby::SSM Parameter Store"]:::lamby
        Railtie["Lamby::Railtie"]:::lamby
    end

    %% Rack Application
    subgraph "Rack Application"
        direction TB
        Middleware["Rack Middleware Stack"]:::app
        Rails["Rails Router → Controllers → Views/Models"]:::app
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        Dummy["Dummy Rails App"]:::test
        HT["handler_test.rb"]:::test
        PCT["proxy_context_test.rb"]:::test
        PST["proxy_server_test.rb"]:::test
        RHT["rack_http_test.rb"]:::test
        RST["rack_rest_test.rb"]:::test
        AT["rack_alb_test.rb"]:::test
        CM["cold_start_metrics_test.rb"]:::test
        SSMT["ssm_parameter_store_test.rb"]:::test
    end

    %% Flows
    FG -->|"HTTP Request"| Handler
    AG1 -->|"REST Event v1"| Handler
    AG2 -->|"REST Event v2"| Handler
    ALB -->|"ALB Event"| Handler

    Handler -->|".wrap(event,context)"| ProxyCtx
    Handler -->|".emitMetrics()"| ColdMetrics
    Handler -->|".log()"| Logger
    Handler -->|".initConfig()"| Config
    Config -->|"fetch params"| SSMInt
    SSMInt -->|"Get Parameter"| SSM_AWS
    ProxyCtx -->|".handle()"| ProxySrv

    ProxySrv -->|".toRack() v1"| AdapterHTTP
    ProxySrv -->|".toRack() v2"| AdapterREST
    ProxySrv -->|".toRack() ALB"| AdapterALB

    AdapterHTTP -->|"Rack::Request"| Middleware
    AdapterREST -->|"Rack::Request"| Middleware
    AdapterALB -->|"Rack::Request"| Middleware

    Middleware -->|"dispatch"| Rails
    Rails -->|"Rack::Response"| ProxySrv

    ProxySrv -->|"Lambda Response"| Handler
    Handler -->|"return response"| CW

    %% Test flows
    Dummy -->|"invokes"| Handler
    Handler --> HT
    ProxyCtx --> PCT
    ProxySrv --> PST
    AdapterHTTP --> RHT
    AdapterREST --> RST
    AdapterALB --> AT
    ColdMetrics --> CM
    SSMInt --> SSMT

    %% Click Events
    click Handler "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/handler.rb"
    click ProxyCtx "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/proxy_context.rb"
    click ProxySrv "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/proxy_server.rb"
    click AdapterHTTP "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/rack_http.rb"
    click AdapterREST "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/rack_rest.rb"
    click AdapterALB "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/rack_alb.rb"
    click ColdMetrics "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/cold_start_metrics.rb"
    click Logger "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/logger.rb"
    click Debug "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/debug.rb"
    click Config "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/config.rb"
    click SSMInt "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/ssm_parameter_store.rb"
    click Railtie "https://github.com/rails-lambda/lamby/blob/master/lib/lamby/railtie.rb"
    click Dummy "https://github.com/rails-lambda/lamby/tree/master/test/dummy_app"
    click HT "https://github.com/rails-lambda/lamby/blob/master/test/handler_test.rb"
    click PCT "https://github.com/rails-lambda/lamby/blob/master/test/proxy_context_test.rb"
    click PST "https://github.com/rails-lambda/lamby/blob/master/test/proxy_server_test.rb"
    click RHT "https://github.com/rails-lambda/lamby/blob/master/test/rack_http_test.rb"
    click RST "https://github.com/rails-lambda/lamby/blob/master/test/rack_rest_test.rb"
    click AT "https://github.com/rails-lambda/lamby/blob/master/test/rack_alb_test.rb"
    click CM "https://github.com/rails-lambda/lamby/blob/master/test/cold_start_metrics_test.rb"
    click SSMT "https://github.com/rails-lambda/lamby/blob/master/test/ssm_parameter_store_test.rb"

    %% Styles
    classDef aws fill:#e0f7e9,stroke:#1b5e20;
    classDef lamby fill:#ffe0b2,stroke:#e65100;
    classDef app fill:#bbdefb,stroke:#0d47a1;
    classDef test fill:#eeeeee,stroke:#424242,stroke-dasharray: 5 5;
```
