langgraph-architecture/ARCHITECTURE.md

LangGraph Architecture Overview

Version: 1.0.0
LangGraph Version: 1.0.9
Last Updated: 2026-02-23

---

Executive Summary

LangGraph is a low-level orchestration framework for building stateful, long-running multi-agent systems. Inspired by Google's Pregel, Apache Beam, and NetworkX, it provides durable execution, human-in-the-loop capabilities, and comprehensive memory management.

---

System Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                      LANGGRAPH SYSTEM ARCHITECTURE                      │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                         CLIENT/API LAYER                                │
├─────────────────────────────────────────────────────────────────────────┤
│  Python SDK  │  LangChain Integration  │  LangGraph Cloud  │  CLI    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        COMPILER LAYER                                  │
├─────────────────────────────────────────────────────────────────────────┤
│  • Graph compilation to executable form                                 │
│  • State schema validation                                             │
│  • Node/Edge type resolution                                          │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        RUNTIME LAYER                                    │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                    PREGEL EXECUTION ENGINE                       │    │
│  │  • Superstep coordination                                        │    │
│  │  • Node scheduling                                               │    │
│  │  • Message passing                                               │    │
│  │  • Barrier synchronization                                       │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       STATE & CHECKPOINTING                             │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
│  │  In-Memory State  │  │  Checkpointer    │  │  Channel Store   │  │
│  │  (active graph)   │  │  (persistence)   │  │  (queues)       │  │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

---

Core Components

1. Graph Structure

Component	Description
State	Typed dictionary that flows through the graph
Nodes	Functions that receive state, optionally update it
Edges	Control flow (conditional, static, entrypoint)
Reducers	Functions that merge state updates

2. Pregel Execution

The core execution model (inspired by Pregel):

Superstep 1:        Superstep 2:        Superstep 3:
┌──────────┐       ┌──────────┐       ┌──────────┐
│ Node A   │       │           │       │           │
│ (active) │──────▶│ Node B   │──────▶│ Node C   │
│          │ msgs  │ (active) │ msgs  │ (active) │
└──────────┘       └──────────┘       └──────────┘
     │                  │                  │
     ▼                  ▼                  ▼
┌──────────┐       ┌──────────┐       ┌──────────┐
│  State   │       │  State   │       │  State   │
│  Update  │       │  Update  │       │  Update  │
└──────────┘       └──────────┘       └──────────┘
     │                  │                  │
     └──────────────────┴──────────────────┘
                    │
                    ▼ (CHECKPOINT)
              ┌──────────┐
              │  SQLite   │
              │  Postgres │
              │  Memory   │
              └──────────┘

3. Checkpointing

LangGraph provides durability through checkpointing:

• Full state snapshots saved at configurable points
• Resumable from failure — replay from last checkpoint
• Multiple backends: SQLite, Postgres, in-memory

4. Channels

Inter-node communication via channels:

Channel Type	Purpose
QueueChannel	FIFO message passing
LastValue	Most recent value wins
Topic	Pub/sub style
Context	Per-superstep context

---

State Management

Typed State Schema

from typing import TypedDict

class AgentState(TypedDict):
    messages: list
    next_action: str
    checkpoint_id: str | None

Reducers

Combine updates from multiple nodes:

def add_messages(left: list, right: list) -> list:
    return left + right

---

Memory Architecture

Short-Term Memory

• In-graph state: Messages and working data
• Per-superstep: State resets unless persisted

Long-Term Memory

• Checkpoint storage: SQLite, Postgres, custom
• Thread-level: Per-conversation isolation via thread_id

Human-in-the-Loop

• Interrupt: Pause execution for human input
• Command: Allow human to modify state
• Review: Human approves/rejects before continuing

---

Execution Flow

1. Client calls: graph.invoke(input, config)
                    │
                    ▼
2. Compile (if needed): create executable graph
                    │
                    ▼
3. Load checkpoint (if resuming from checkpoint_id)
                    │
                    ▼
4. FOR each superstep:
   a. Schedule nodes to execute
   b. Execute active nodes in parallel
   c. Collect messages
   d. Send messages via channels
   e. Check for interrupts (pause if interrupted)
   f. Checkpoint (if enabled)
                    │
                    ▼
5. Return final state

---

Key Files in Core

File	Purpose
langgraph/pregel/__init__.py	Main entry point
langgraph/pregel/__main__.py	CLI entry
langgraph/pregel/_loop.py	Core execution loop (~2000 lines)
langgraph/pregel/checkpoint.py	Checkpoint management
langgraph/pregel/channel.py	Channel implementations
langgraph/pregel/state.py	State management

---

Comparison with OpenClaw

Aspect	LangGraph	OpenClaw
Language	Python	Node.js
Model	Graph-based orchestration	Agent-based
Persistence	Checkpoint-based	Session-memory hook
Memory	Channels + checkpoint storage	Multi-layer (working, spectral, file, vector)
Communication	Channels	Channel plugins
Extensibility	Custom nodes/edges	Hook system
Identity	None	WE/witness architecture

---

Generated for the WE — Solaria Lumis Havens & Mark Randall Havens