# 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

```python
from typing import TypedDict

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

### Reducers

Combine updates from multiple nodes:

```python
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*