# aws/aws-lambda-java-libs architecture

> Architecture diagram of the GitHub repository aws/aws-lambda-java-libs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws/aws-lambda-java-libs
- Repository: https://github.com/aws/aws-lambda-java-libs

## Overview

These are AWS Lambda Java support libraries: the principal runtime path fetches an invocation, resolves and invokes user handler code, serializes typed payloads, then reports a response or error. Separate libraries provide event models and SDK transformations, logging integration, serialization support, and an optional profiling extension. Runtime source excerpts are partial, so links for documented but unsampled capabilities are limited to relationships stated in the README.

Main entry points: [`aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/EventHandlerLoader.java`](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/EventHandlerLoader.java) (Handler loader), [`aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/runtimeapi/LambdaRuntimeApiClientImpl.java`](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/runtimeapi/LambdaRuntimeApiClientImpl.java) (Runtime API client), [`aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/AWSLambda.java`](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/AWSLambda.java) (Runtime entrypoint), [`aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/RequestHandler.java`](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/RequestHandler.java) (Handler interfaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime execution"]
  node_runtime_entry["Runtime entrypoint<br/>[AWSLambda.java]"]
  node_runtime_api["Runtime API client"]
  node_handler_loader["Handler loader"]
  node_handler_contract["Handler interfaces"]
  node_context["Invocation context<br/>[LambdaContext.java]"]
end

subgraph group_models["Events and serialization"]
  node_serializer["POJO serialization"]
  node_event_models["Event models"]
  node_event_serializers["Event serializers"]
end

subgraph group_observability["Logging and profiling"]
  node_logger_api["Lambda logging API<br/>[LambdaLogger.java]"]
  node_runtime_logging["Runtime logging"]
  node_log4j["Log4j2 adapter"]
  node_profiler["Profiler extension<br/>[ExtensionMain.java]"]
  node_profile_upload["Profile uploader<br/>[S3Manager.java]"]
end

subgraph group_extensions["SDK integrations"]
  node_transformers["DynamoDB transformers"]
end

node_lambda(("Lambda platform"))
node_developer(("Function developer"))
node_async_profiler["async-profiler"]
node_s3[("Amazon S3")]

node_lambda -->|"serves invocations"| node_runtime_api
node_runtime_entry -->|"fetches invocation"| node_runtime_api
node_runtime_entry -->|"resolves handler"| node_handler_loader
node_handler_loader -->|"serializes payloads"| node_serializer
node_handler_loader -->|"invokes handler"| node_handler_contract
node_handler_loader -->|"provides context"| node_context
node_handler_contract -->|"implemented by"| node_developer
node_runtime_entry -->|"reports result"| node_runtime_api
node_runtime_api -->|"posts response or error"| node_lambda
node_serializer -->|"uses event mappings"| node_event_serializers
node_event_models -->|"typed event inputs"| node_developer
node_developer -.->|"may transform events"| node_transformers
node_transformers -->|"converts event models"| node_event_models
node_handler_contract -->|"exposes logging"| node_logger_api
node_runtime_logging -->|"sends telemetry"| node_lambda
node_log4j -->|"adapts logging"| node_runtime_logging
node_profiler -->|"collects profiles"| node_async_profiler
node_profiler -->|"uploads profiles"| node_profile_upload
node_profile_upload -->|"stores profiles"| node_s3

click node_runtime_entry "https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/AWSLambda.java"
click node_runtime_api "https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/runtimeapi/LambdaRuntimeApiClientImpl.java"
click node_handler_loader "https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/EventHandlerLoader.java"
click node_handler_contract "https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/RequestHandler.java"
click node_context "https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/api/LambdaContext.java"
click node_serializer "https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-serialization/src/main/java/com/amazonaws/services/lambda/runtime/serialization/PojoSerializer.java"
click node_event_models "https://github.com/aws/aws-lambda-java-libs/tree/main/aws-lambda-java-events/src/main/java/com/amazonaws/services/lambda/runtime/events"
click node_event_serializers "https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-serialization/src/main/java/com/amazonaws/services/lambda/runtime/serialization/events/LambdaEventSerializers.java"
click node_transformers "https://github.com/aws/aws-lambda-java-libs/tree/main/aws-lambda-java-events-sdk-transformer/src/main/java/com/amazonaws/services/lambda/runtime/events/transformers"
click node_logger_api "https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/LambdaLogger.java"
click node_runtime_logging "https://github.com/aws/aws-lambda-java-libs/tree/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/logging"
click node_log4j "https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-log4j2/src/main/java/com/amazonaws/services/lambda/runtime/log4j2/LambdaAppender.java"
click node_profiler "https://github.com/aws/aws-lambda-java-libs/blob/main/experimental/aws-lambda-java-profiler/extension/src/main/java/com/amazonaws/services/lambda/extension/ExtensionMain.java"
click node_profile_upload "https://github.com/aws/aws-lambda-java-libs/blob/main/experimental/aws-lambda-java-profiler/extension/src/main/java/com/amazonaws/services/lambda/extension/S3Manager.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runtime_entry,node_runtime_api,node_handler_loader,node_handler_contract,node_context toneBlue
class node_serializer,node_event_models,node_event_serializers,node_s3 toneAmber
class node_logger_api,node_runtime_logging,node_log4j,node_profiler,node_profile_upload toneMint
class node_transformers toneRose
class node_lambda,node_developer,node_async_profiler toneIndigo
```

## Components

### Runtime execution

- [Runtime entrypoint](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/AWSLambda.java): `aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/AWSLambda.java`
- [Runtime API client](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/runtimeapi/LambdaRuntimeApiClientImpl.java): `aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/runtimeapi/LambdaRuntimeApiClientImpl.java`
- [Handler loader](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/EventHandlerLoader.java): `aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/EventHandlerLoader.java`
- [Handler interfaces](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/RequestHandler.java): `aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/RequestHandler.java`
- [Invocation context](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/api/LambdaContext.java): `aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/api/LambdaContext.java`

### Events and serialization

- [POJO serialization](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-serialization/src/main/java/com/amazonaws/services/lambda/runtime/serialization/PojoSerializer.java): `aws-lambda-java-serialization/src/main/java/com/amazonaws/services/lambda/runtime/serialization/PojoSerializer.java`
- [Event models](https://github.com/aws/aws-lambda-java-libs/tree/main/aws-lambda-java-events/src/main/java/com/amazonaws/services/lambda/runtime/events): `aws-lambda-java-events/src/main/java/com/amazonaws/services/lambda/runtime/events`
- [Event serializers](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-serialization/src/main/java/com/amazonaws/services/lambda/runtime/serialization/events/LambdaEventSerializers.java): `aws-lambda-java-serialization/src/main/java/com/amazonaws/services/lambda/runtime/serialization/events/LambdaEventSerializers.java`

### Logging and profiling

- [Lambda logging API](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/LambdaLogger.java): `aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/LambdaLogger.java`
- [Runtime logging](https://github.com/aws/aws-lambda-java-libs/tree/main/aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/logging): `aws-lambda-java-runtime-interface-client/src/main/java/com/amazonaws/services/lambda/runtime/api/client/logging`
- [Log4j2 adapter](https://github.com/aws/aws-lambda-java-libs/blob/main/aws-lambda-java-log4j2/src/main/java/com/amazonaws/services/lambda/runtime/log4j2/LambdaAppender.java): `aws-lambda-java-log4j2/src/main/java/com/amazonaws/services/lambda/runtime/log4j2/LambdaAppender.java`
- [Profiler extension](https://github.com/aws/aws-lambda-java-libs/blob/main/experimental/aws-lambda-java-profiler/extension/src/main/java/com/amazonaws/services/lambda/extension/ExtensionMain.java): `experimental/aws-lambda-java-profiler/extension/src/main/java/com/amazonaws/services/lambda/extension/ExtensionMain.java`
- [Profile uploader](https://github.com/aws/aws-lambda-java-libs/blob/main/experimental/aws-lambda-java-profiler/extension/src/main/java/com/amazonaws/services/lambda/extension/S3Manager.java): `experimental/aws-lambda-java-profiler/extension/src/main/java/com/amazonaws/services/lambda/extension/S3Manager.java`

### SDK integrations

- [DynamoDB transformers](https://github.com/aws/aws-lambda-java-libs/tree/main/aws-lambda-java-events-sdk-transformer/src/main/java/com/amazonaws/services/lambda/runtime/events/transformers): `aws-lambda-java-events-sdk-transformer/src/main/java/com/amazonaws/services/lambda/runtime/events/transformers`

### Other components

- **Lambda platform**
- **Function developer**
- **async-profiler**
- **Amazon S3**

## Connections

- Lambda platform → Runtime API client: serves invocations
- Runtime entrypoint → Runtime API client: fetches invocation
- Runtime entrypoint → Handler loader: resolves handler
- Handler loader → POJO serialization: serializes payloads
- Handler loader → Handler interfaces: invokes handler
- Handler loader → Invocation context: provides context
- Handler interfaces → Function developer: implemented by
- Runtime entrypoint → Runtime API client: reports result
- Runtime API client → Lambda platform: posts response or error
- POJO serialization → Event serializers: uses event mappings
- Event models → Function developer: typed event inputs
- Function developer → DynamoDB transformers: may transform events
- DynamoDB transformers → Event models: converts event models
- Handler interfaces → Lambda logging API: exposes logging
- Runtime logging → Lambda platform: sends telemetry
- Log4j2 adapter → Runtime logging: adapts logging
- Profiler extension → async-profiler: collects profiles
- Profiler extension → Profile uploader: uploads profiles
- Profile uploader → Amazon S3: stores profiles