GraphFlow

A self-hostable runtime and API platform for executing LangGraph graphs on your own infrastructure — a local-deployable alternative to the managed LangGraph Platform. GraphFlow provides graph execution with durable checkpointing, real-time event streaming, thread/run/assistant management, and an MCP server interface, all behind a REST API.

Status

This is a personal reference implementation built as a side project. It is shared publicly as an architectural reference for engineers I work with. It is provided as-is, is not actively maintained, and is not accepting issues or pull requests. Please don't build production systems on it.

What it does

• Graph execution engine — runs compiled LangGraph StateGraphs with PostgreSQL-backed checkpointing (AsyncPostgresSaver) and multi-mode streaming (values / messages / updates / events).
• Real-time streaming — Redis pub/sub fan-out to Server-Sent Events, with terminal-event handling that closes connections per the LangGraph SSE model.
• Platform API — REST endpoints for assistants, threads, runs, run steps, packages, and streaming, with an auth layer (middleware + dependencies).
• Thread state & history — durable thread state with history, backed by PostgreSQL materialized views and purpose-built filtering indexes.
• MCP server — exposes deployed graphs as tools over the Model Context Protocol.
• Deployable graph packages — load and run graph "packages" on a single self-hosted platform.

Architecture

backend/src/graphflow/

api/ REST API — routers, auth (middleware/dependencies), models

runtime/ Graph runtime: engine, package loader

execution/ Graph executor (run lifecycle + streaming orchestration)

streaming/ Redis pub/sub → SSE streaming service

storage/ Repositories + services + SQLAlchemy models + migrations

mcp_server/ MCP protocol server

deployment/ Graph & package deployment

monitoring/ Error visibility / observability

cli/ Command-line interface

Stack: Python, FastAPI, LangGraph, PostgreSQL (Alembic migrations + PLpgSQL), Redis, SQLAlchemy (async), Server-Sent Events, MCP.

Where to start reading

1. backend/src/graphflow/streaming/streaming_service.py — clean, single-responsibility Redis→SSE service; a good sense of the code style.
2. The threads feature end-to-end: api/routers/threads.py → storage/services/thread_state_service.py → the thread-state materialized-view migration in backend/alembic/versions/.
3. runtime/engine.py and execution/graph_executor.py — the execution core and checkpointing/streaming integration.

Known limitations

Being candid, since this is a reference impl and not a product:

• Two execution paths (runtime/engine.py and execution/graph_executor.py) coexist from an in-progress runtime consolidation.
• Logging is intentionally verbose for development.
• Typing style is not yet uniform across all modules.

Reference Docs

A small set of documentation for developers building and deploying agent graphs to the system:

Architecture & subsystems

• Streaming — Redis pub/sub → SSE event streaming
• MCP Developer Guide — using the MCP server interface
• MCP Database Usage
• Error Visibility System — error propagation & observability
• Auth — API authentication layer
• Storage Layer — repositories, services, and models

Features & API guides

• Thread Search
• Thread Search API Guide
• Threads Filtering Examples
• Streaming Example

Developer experience

• Developer Error Guide
• DX Optimization Guide

Component READMEs

• Backend
• Scripts
• MCP Tests