LangGraph-GUI - AI Quick Reference

A visual node-based workflow builder for LLM-powered applications using LangGraph.

Project Overview

Purpose: GUI for creating and executing LLM workflows visually Version: 2.2.1 License: MIT Architecture: Monorepo with git submodules (frontend, backend, examples)

┌─────────────────────────────────────────────────────────────────┐
│                        User Browser                              │
└─────────────────────────┬───────────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────────┐
│  Frontend (SvelteKit + @xyflow/svelte)        Port 3000         │
│  - Visual node editor for workflow design                       │
│  - Stores graph as nodes/edges in Svelte stores                 │
│  - Exports/imports graph.json                                   │
└─────────────────────────┬───────────────────────────────────────┘
                          │ HTTP API
┌─────────────────────────▼───────────────────────────────────────┐
│  Backend (FastAPI + LangGraph)                Port 5000         │
│  - Executes workflows via LangGraph StateGraph                  │
│  - Multi-user workspaces: /app/src/workspace/{username}/        │
│  - Streams execution output via SSE                             │
└─────────────────────────┬───────────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────────┐
│  Ollama (Local LLM)                           Port 13666        │
│  - NVIDIA CUDA 12.2 base                                        │
│  - Alternative: OpenAI GPT API                                  │
└─────────────────────────────────────────────────────────────────┘

Directory Structure

LangGraph-GUI/
├── backend/                 # Git submodule: FastAPI + LangGraph
│   └── src/
│       ├── main.py          # FastAPI server entry point
│       ├── WorkFlow.py      # LangGraph workflow execution (990+ lines)
│       ├── llm.py           # LLM provider abstraction (OpenAI/Ollama)
│       ├── run_graph.py     # CLI workflow runner
│       ├── NodeData.py      # Node data model
│       ├── process_handler.py  # Background process management
│       └── FileTransmit.py  # File upload/download API
│
├── frontend/                # Git submodule: SvelteKit + Svelte 5
│   └── src/routes/
│       ├── graph/           # Main workflow editor
│       │   ├── +page.svelte # Graph editor page
│       │   ├── flow/        # Graph visualization
│       │   │   ├── graphs.store.svelte.ts  # Reactive state store
│       │   │   ├── node-schema.ts          # Node type definitions
│       │   │   └── node-texture.svelte     # Node rendering
│       │   └── menu/        # UI panels
│       │       ├── sidebar.svelte
│       │       ├── ConfigWindow.svelte
│       │       └── RunWindow.svelte
│       ├── app/             # Chapter/content views
│       └── doc/             # Documentation viewer
│
├── k8s/                     # Kubernetes manifests
│   ├── namespace/           # langgraph-gui namespace
│   ├── *-deployment.yaml    # backend, frontend, ollama
│   ├── *-service.yaml       # ClusterIP services
│   ├── *-ingress.yaml       # TLS ingress rules
│   ├── NV-GPU/              # NVIDIA GPU RuntimeClass
│   └── mime/                # MIME type configmap
│
├── ollama/                  # Ollama container (CUDA 12.2)
├── nginx/                   # Reverse proxy config (auth, rate limit)
├── electron/                # Desktop app wrapper
├── examples/                # Git submodule: example workflows
├── docker-compose.yml       # Local development orchestration
└── .gitmodules              # Submodule definitions

Technology Stack

Layer	Technology
Frontend Framework	SvelteKit 2.16 + Svelte 5
Graph Visualization	@xyflow/svelte 1.0.2
Styling	Tailwind CSS 4
Build Tool	Vite 6.2
Backend Framework	FastAPI (Python 3.12)
Workflow Engine	LangGraph + LangChain
LLM Providers	Ollama (local), OpenAI GPT
Container Runtime	Docker, Kubernetes
GPU Support	NVIDIA CUDA 12.2

Key Files Reference

Backend

File	Purpose
backend/src/main.py:1	FastAPI app with CORS, routes, SSE streaming
backend/src/WorkFlow.py:1	LangGraph StateGraph builder, node execution logic
backend/src/llm.py:22	get_llm() - LLM provider factory (GPT/Ollama)
backend/src/llm.py:73	create_llm_chain() - Prompt template execution
backend/src/run_graph.py	CLI entry: python run_graph.py --llm <model> --key <key>

Frontend

File	Purpose
frontend/src/routes/graph/+page.svelte	Main graph editor page
frontend/src/routes/graph/flow/node-schema.ts:3	NodeType enum: START, STEP, TOOL, CONDITION, INFO, SUBGRAPH
frontend/src/routes/graph/flow/graphs.store.svelte.ts	Reactive stores: currentNodes, currentEdges
frontend/src/routes/graph/menu/RunWindow.svelte	Workflow execution UI

Node Types

enum NodeType {
  START     // Entry point, initializes state
  STEP      // LLM prompt execution, returns JSON
  TOOL      // Calls registered Python function
  CONDITION // Boolean branch (true_next / false_next)
  INFO      // Display-only information node
  SUBGRAPH  // Nested workflow execution
}

interface JsonNodeData {
  uniq_id: string;
  name: string;
  description: string;      // Prompt template or info text
  nexts: string[];          // Next node IDs (for STEP/TOOL)
  type: string;             // NodeType value
  tool: string;             // Tool function name (for TOOL nodes)
  true_next: string | null; // Condition true branch
  false_next: string | null;// Condition false branch
  ext: { pos_x, pos_y, width, height }; // Visual position
}

Backend API

POST /run/{username}
  Body: { llm_model: string, api_key: string }
  Response: SSE stream of execution output
  Action: Spawns run_graph.py in workspace/{username}/

GET /status/{username}
  Response: { running: boolean }

POST /chatbot/{username}
  Body: { input_string, llm_model, api_key }
  Response: { result: string }

POST /files/{username}/upload
GET  /files/{username}/download/{filename}

Workflow Execution Flow

# PipelineState (TypedDict)
{
  "history": str,    # Accumulated context (append-only, clipped to 16K chars)
  "task": str,       # Current task description
  "condition": bool  # For CONDITION node branching
}

# Execution: START → STEP/TOOL → CONDITION → next → ... → END

1. Frontend saves graph.json to backend workspace
2. User clicks Run → POST /run/{username} with LLM config
3. Backend spawns run_graph.py as subprocess
4. LangGraph builds StateGraph from nodes
5. Each node executes based on type:
   • STEP: LLM chain with prompt template → JSON output
   • TOOL: Call tool_registry[tool_name](*args)
   • CONDITION: Evaluate and route to true_next/false_next
6. Output streams via SSE to frontend

Environment Variables

# Backend
BACKEND_PORT=5000
OLLAMA_BASE_URL=http://ollama:13666
OPENAI_API_KEY=sk-...  # For GPT models

# Ollama
OLLAMA_HOST=0.0.0.0:13666

Development Commands

# Docker Compose (local dev)
docker-compose up --build

# Individual services
cd frontend && npm run dev      # Port 3000
cd backend && python src/main.py # Port 5000

# Kubernetes
kubectl apply -f k8s/namespace/
kubectl apply -f k8s/

# Frontend testing
cd frontend
npm run test:unit    # Vitest
npm run test:e2e     # Playwright
npm run lint         # ESLint + Prettier

Git Submodules

# Clone with submodules
git clone --recursive <repo-url>

# Update submodules
git submodule update --init --recursive

# Submodule repos:
# - backend  → LangGraph-GUI-backend
# - frontend → LangGraph-GUI-Svelte
# - examples → examples.git

Key Concepts

1. SSOT (Single Source of Truth): Nodes are the source; edges derive from nexts, true_next, false_next
2. History Clipping: clip_history() limits context to 16K chars
3. Tool Registry: Python decorator @tool registers functions for TOOL nodes
4. Subgraph Registry: Nested workflows loaded from JSON files
5. Multi-user: Each user has isolated workspace at /app/src/workspace/{username}/

Common Tasks

Add a new node type

1. Add to NodeType enum in frontend/src/routes/graph/flow/node-schema.ts
2. Update node rendering in node-texture.svelte
3. Add execution logic in backend/src/WorkFlow.py

Add a new LLM provider

1. Update get_llm() in backend/src/llm.py
2. Add detection pattern (e.g., if "provider" in llm_model.lower())

Add a new tool

# backend/src/WorkFlow.py
@tool
def my_tool(arg1: str, arg2: int) -> str:
    """Description of what this tool does."""
    return f"Result: {arg1}, {arg2}"

Deploy to Kubernetes

1. Build and push images to registry (127.0.0.1:7000)
2. Update hostPath in k8s/*-deployment.yaml to absolute paths
3. Apply manifests: kubectl apply -f k8s/

File Formats

graph.json

{
  "nodes": [
    {
      "uniq_id": "node_1",
      "name": "Start",
      "description": "",
      "type": "START",
      "nexts": ["node_2"],
      "tool": "",
      "true_next": null,
      "false_next": null,
      "ext": { "pos_x": 100, "pos_y": 100 }
    }
  ]
}

Troubleshooting

Issue	Solution
CORS errors	Check allow_origins in backend/src/main.py:30
Ollama connection failed	Verify OLLAMA_BASE_URL env var, check network
GPU not detected	Ensure NVIDIA drivers, check nvidia-smi
Submodule empty	Run git submodule update --init --recursive
K8s hostPath issues	Use absolute paths in deployment yamls