# justinram11/langgraph-checkpoint-dynamodb architecture

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

- Interactive diagram: https://gitdiagram.com/justinram11/langgraph-checkpoint-dynamodb
- Repository: https://github.com/justinram11/langgraph-checkpoint-dynamodb

## Overview

##### Project type and purpose
- This is an open-source Python library (a LangGraph “CheckpointSaver” plugin) that implements checkpoint and write persistence on AWS DynamoDB.
- Its sole responsibility is to provide a drop-in saver for LangGraph workflows, storing checkpoint metadata and per-task write records in two DynamoDB tables.

##### File structure
- Top-level files:
- setup.py / requirements.txt → packaging and dependencies (e.g., boto3)
- README.md → high-level usage and AWS resource requirements
- Package directory (langgraph_checkpoint_dynamodb):
- __init__.py → exposes DynamoDBSaver
- saver.py → core logic for checkpoints
- write.py → logic for persisting individual write records

##### Key architecture from README
- Two DynamoDB tables (“checkpoints” and “writes”)
- Optional custom AWS client configuration (region, keys)
- Integration point: user passes DynamoDBSaver into workflow.compile()

##### Main components
a. LangGraph Workflow (client application)
b. DynamoDBSaver library (Python module)
- Saver component (saver.py)
- Write component (write.py)
- AWS SDK / DynamoDB client (boto3)
c. AWS DynamoDB service
- Checkpoints Table
- Writes Table
d. Optional: Client Configuration object (region, credentials)

##### Relationships and data flow
- LangGraph Workflow invokes DynamoDBSaver API →
- DynamoDBSaver uses boto3 client →
- PutItem calls to CheckpointsTable
- PutItem/BatchWriteItem calls to WritesTable

##### Architectural patterns & design principles
- Adapter/Plugin pattern: DynamoDBSaver implements a CheckpointSaver interface.
- Dependency Injection: Supports passing in custom client configuration.
- Single Responsibility: saver.py handles checkpoint metadata; write.py handles per-task writes.

##### Putting it all together
- Top layer: LangGraph Workflow
- Middle layer: DynamoDBSaver library
- Internal layers: saver.py, write.py
- AWS SDK client
- Bottom layer: AWS DynamoDB (two tables)
- Optional side-input: ClientConfig object injected into SDK client

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top layer: User application
    UserApp["LangGraph Workflow"]:::external
    ClientConfig["ClientConfig Object"]:::external

    %% Library layer
    subgraph "DynamoDBSaver Library"
        direction TB
        CheckpointSaver["CheckpointSaver Plugin"]:::code
        SaverComp["Saver Component (saver.py)"]:::code
        WriteComp["Write Component (write.py)"]:::code
        BotoClient["AWS SDK / DynamoDB Client (boto3)"]:::sdk
    end

    %% AWS Resources
    subgraph "AWS Account"
        direction TB
        CheckpointsTable["Checkpoints Table"]:::db
        WritesTable["Writes Table"]:::db
    end

    %% Project root files
    subgraph "Project Root"
        direction TB
        Setup["setup.py"]:::code
        Req["requirements.txt"]:::code
        Readme["README.md"]:::external
    end

    %% Connections
    UserApp -->|"uses plugin"| CheckpointSaver
    ClientConfig -->|"injects config into"| BotoClient
    CheckpointSaver -->|"save_checkpoint()"| SaverComp
    CheckpointSaver -->|"write_record()"| WriteComp
    SaverComp -->|"PutItem"| BotoClient
    WriteComp -->|"BatchWriteItem"| BotoClient
    BotoClient -->|"DynamoDB API"| CheckpointsTable
    BotoClient -->|"DynamoDB API"| WritesTable

    %% Click Events
    click CheckpointSaver "https://github.com/justinram11/langgraph-checkpoint-dynamodb/blob/main/langgraph_checkpoint_dynamodb/__init__.py"
    click SaverComp "https://github.com/justinram11/langgraph-checkpoint-dynamodb/blob/main/langgraph_checkpoint_dynamodb/saver.py"
    click WriteComp "https://github.com/justinram11/langgraph-checkpoint-dynamodb/blob/main/langgraph_checkpoint_dynamodb/write.py"
    click BotoClient "https://github.com/justinram11/langgraph-checkpoint-dynamodb/blob/main/requirements.txt"
    click Setup "https://github.com/justinram11/langgraph-checkpoint-dynamodb/blob/main/setup.py"
    click Readme "https://github.com/justinram11/langgraph-checkpoint-dynamodb/blob/main/README.md"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef sdk fill:#D0FFD0,stroke:#228B22,stroke-width:1px
    classDef db fill:#FFE0B2,stroke:#FF8C00,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#737373,stroke-width:1px
```
