# 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 ```typescript 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 ```python # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```python # 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 ```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 |