How langchain-ai/langgraphjs works
1. This is a TypeScript/JavaScript monorepo for LangGraph.js.
The repo ships the core orchestration engine, server/runtime components, client SDKs, framework-specific UI bindings, persistence backends, CLI tools, docs, and many runnable examples.
2. The central runtime is libs/langgraph-core.
This package contains the low-level graph execution model: channels, state reducers, prebuilt agent executors, and the Pregel-style runner/loop. It is the main “engine” layer and has no direct HTTP/UI concerns.
3. libs/langgraph is the public umbrella package.
It re-exports selected core capabilities to provide the primary developer-facing API surface. Architecturally it sits above langgraph-core and is meant to be the simple import target for application authors.
4. Stateful execution and persistence are split into checkpoint packages.
libs/checkpoint provides the generic checkpoint/store abstractions and in-memory implementations.
Backend-specific packages extend that model for Postgres, MongoDB, Redis, and SQLite. These packages are the persistence boundary for thread state, replay, time travel, and long-running workflows.
5. libs/langgraph-api is the server-side control plane.
It exposes HTTP APIs for assistants, runs, threads, store access, auth, streams, webhooks, and metadata. It also loads user graphs, parses project config, manages persistence, and mediates between external requests and the graph runtime.
6. Graph loading is a distinct subsystem inside langgraph-api.
The graph/, storage/, ui/, auth/, and http/ folders separate concerns: loading user code, persisting runtime data, attaching UI assets, enforcing auth, and serving the network API. This is the main boundary between “user agent code” and “managed runtime”.
7. Streaming is a first-class data flow across the stack.
Graph execution produces incremental updates/tokens/events in langgraph-core, langgraph-api forwards them over HTTP/SSE-style streams, and libs/sdk plus the framework-specific SDKs consume and normalize those streams for UI rendering.
8. libs/sdk is the generic client and UI orchestration layer.
It contains API clients, auth helpers, SSE/stream utilities, and higher-level UI orchestration primitives such as message management, branching, interrupts, queues, and agent/session helpers. This package is the bridge from backend streams to frontend state.
9. Framework SDKs adapt the generic SDK to UI frameworks.
libs/sdk-react, libs/sdk-svelte, libs/sdk-vue, libs/sdk-angular, and libs/sdk-angular wrap the shared streaming/state logic for each frontend ecosystem. They are thin integration layers, not separate business logic stacks.
10. **The libs/sdk-* packages and libs/langgraph-ui support UI composition.**
langgraph-ui provides tooling for bundling/rendering UI assets, while the framework SDKs provide reusable stream/thread/context patterns. This is important for diagramming because the UI layer is intentionally decoupled from the graph engine.
11. libs/langgraph-cli and libs/create-langgraph support project lifecycle.
The CLI handles local dev, build, Docker/Cloudflare-oriented workflows, project bootstrapping, and packaging concerns. create-langgraph is the scaffolder that generates new LangGraph applications and agent templates.
12. libs/langgraph-supervisor, libs/langgraph-swarm, and libs/langgraph-cua add specialized orchestration patterns.
Supervisor/swarm packages model multi-agent handoff and coordination. CUA adds computer-use agent nodes like VM creation and action execution. These are extensions built on top of the core orchestration model.
13. The repo has strong compatibility and environment-test boundaries.
internal/environment_tests validates package exports across CJS, ESM, bundlers, Vite, Cloudflare, Vercel, and TypeScript compilation. This indicates the distribution boundary is a major architectural concern, not just runtime behavior.
14. Docs and examples are treated as part of the product architecture.
docs/ is a full MkDocs-based documentation site with scripts that convert notebooks and generate reference material. examples/ contains many runnable apps and notebooks demonstrating agent patterns, UI integrations, persistence, and deployment flows.
15. Typical end-to-end flow is: app code → core graph → checkpoints → API/stream → SDK/UI.
User-authored agent graphs are executed by langgraph-core, state is persisted via checkpoint backends, langgraph-api exposes the runtime over network APIs, and sdk/framework SDKs render streamed progress and interactive controls in client apps.
Main entry points: langgraph-core langgraph-core · langgraph-api langgraph-api · sdk sdk · checkpoint checkpoint
Components 23
Runtime
Core graph execution and orchestration layers.
- langgraph-core · Low-level execution model: channels, state, prebuilt agents, and Pregel-style runtime.
libs/langgraph-core - langgraph · Umbrella package re-exporting selected core capabilities for application authors.
libs/langgraph
Persistence
Checkpoint and store backends for durable state.
- checkpoint · Generic checkpoint/store abstractions plus in-memory implementations.
libs/checkpoint - checkpoint-postgres · Postgres persistence backend with migrations and store implementation.
libs/checkpoint-postgres - checkpoint-mongodb · MongoDB-backed checkpoint implementation.
libs/checkpoint-mongodb - checkpoint-redis · Redis-backed checkpoint and store implementation.
libs/checkpoint-redis - checkpoint-sqlite · SQLite checkpoint backend for lightweight durable storage.
libs/checkpoint-sqlite
Control Plane
Server, CLI, and project lifecycle tooling.
- langgraph-api · HTTP API server that loads graphs, serves runs/threads/store/auth, and streams execution.
libs/langgraph-api - langgraph-cli · Local development, build, Docker/Cloudflare workflows, and deployment tooling.
libs/langgraph-cli - create-langgraph · Project and template generator for new LangGraph applications.
libs/create-langgraph
Clients & UI
SDKs and UI integration layers for consuming streams.
- sdk · Generic client, auth, SSE, and UI orchestration layer for consuming LangGraph services.
libs/sdk - sdk-react · React bindings for the shared streaming and thread orchestration logic.
libs/sdk-react - sdk-svelte · Svelte bindings for the shared streaming and thread orchestration logic.
libs/sdk-svelte - sdk-vue · Vue bindings for the shared streaming and thread orchestration logic.
libs/sdk-vue - sdk-angular · Angular bindings for the shared streaming and thread orchestration logic.
libs/sdk-angular - langgraph-ui · Tooling for bundling and rendering UI assets for LangGraph applications.
libs/langgraph-ui
Ecosystem
Specialized orchestration packages, docs, examples, and validation.
- langgraph-supervisor · Supervisor-style multi-agent handoff and coordination patterns.
libs/langgraph-supervisor - langgraph-swarm · Swarm-oriented agent coordination and handoff patterns.
libs/langgraph-swarm - langgraph-cua · Computer-use agent nodes for VM creation and action execution.
libs/langgraph-cua - docs · MkDocs-based docs, reference generation scripts, and notebook conversion tooling.
docs - examples · Runnable apps and notebooks demonstrating agents, UI integrations, persistence, and deployment.
examples - environment tests · Export and packaging validation across CJS, ESM, bundlers, Vite, Cloudflare, Vercel, and TypeScript.
internal/environment_tests - build tools · Internal build utilities and benchmark harnesses used by the repository.
internal/build
Connections 24
- langgraph → langgraph-core: re-exports · Public API surface builds on the core engine.
- langgraph-core → checkpoint: persists via · Runtime state can be checkpointed through the shared persistence abstractions.
- checkpoint-postgres → checkpoint: extends · Backend-specific persistence implementation.
- checkpoint-mongodb → checkpoint: extends · Backend-specific persistence implementation.
- checkpoint-redis → checkpoint: extends · Backend-specific persistence implementation.
- checkpoint-sqlite → checkpoint: extends · Backend-specific persistence implementation.
- langgraph-api → langgraph-core: executes graphs · Server loads user graphs and runs them through the engine.
- langgraph-api → checkpoint: stores state · API runtime uses checkpoint/store abstractions for durable workflow state.
- langgraph-api → langgraph-ui: serves ui · Server can attach or load UI assets for managed apps.
- langgraph-api → sdk: streams to · HTTP and streaming responses are consumed by client SDKs.
- langgraph-cli → langgraph-api: starts runtime · CLI manages local dev and deployment entrypoints for the API/server runtime.
- create-langgraph → langgraph-cli: bootstraps · Scaffolding feeds the project lifecycle supported by the CLI.
- sdk → langgraph-api: consumes api · Generic client layer talks to the server control plane and stream endpoints.
- sdk-react → sdk: adapts · Framework wrapper over the shared SDK logic.
- sdk-svelte → sdk: adapts · Framework wrapper over the shared SDK logic.
- sdk-vue → sdk: adapts · Framework wrapper over the shared SDK logic.
- sdk-angular → sdk: adapts · Framework wrapper over the shared SDK logic.
- langgraph-supervisor → langgraph-core: builds on · Specialized orchestration pattern implemented on top of the core engine.
- langgraph-swarm → langgraph-core: builds on · Specialized orchestration pattern implemented on top of the core engine.
- langgraph-cua → langgraph-core: builds on · Computer-use nodes are implemented on top of the core engine.
- docs → langgraph-core: documents · Documentation covers the runtime, persistence, server, and SDK layers.
- examples → langgraph-core: demonstrates · Examples show application patterns built on the core engine and surrounding stack.
- environment tests → langgraph: validates exports · Compatibility matrix checks package distribution across runtimes and bundlers.
- build tools → langgraph-cli: supports · Internal tooling assists build and release workflows.