System Architecture

Relevant source files

• Makefile
• README.md
• docs/docs/Components/bundles-nvidia.mdx
• docs/docs/Components/components-embedding-models.mdx
• docs/docs/Components/components-models.mdx
• docs/docs/Components/read-file.mdx
• docs/docs/Components/write-file.mdx
• docs/docs/Develop/concepts-file-management.mdx
• docs/docs/Develop/concepts-voice-mode.mdx
• docs/docs/Get-Started/get-started-installation.mdx
• docs/docs/Support/release-notes.mdx
• docs/static/img/langflow-logo-color-black-solid.svg
• pyproject.toml
• scripts/setup/setup_env.sh
• src/backend/base/langflow/__main__.py
• src/backend/base/langflow/agentic/utils/template_create.py
• src/backend/base/langflow/api/v1/api_key.py
• src/backend/base/langflow/api/v1/chat.py
• src/backend/base/langflow/api/v1/endpoints.py
• src/backend/base/langflow/api/v1/flows.py
• src/backend/base/langflow/api/v1/folders.py
• src/backend/base/langflow/api/v1/login.py
• src/backend/base/langflow/api/v1/schemas.py
• src/backend/base/langflow/api/v1/store.py
• src/backend/base/langflow/custom/custom_component/component.py
• src/backend/base/langflow/custom/custom_component/custom_component.py
• src/backend/base/langflow/custom/utils.py
• src/backend/base/langflow/helpers/folders.py
• src/backend/base/langflow/initial_setup/setup.py
• src/backend/base/langflow/interface/initialize/loading.py
• src/backend/base/langflow/main.py
• src/backend/base/langflow/schema/schema.py
• src/backend/base/langflow/serialization/serialization.py
• src/backend/base/langflow/services/auth/utils.py
• src/backend/base/langflow/services/database/models/api_key/crud.py
• src/backend/base/langflow/services/database/service.py
• src/backend/base/langflow/services/settings/base.py
• src/backend/base/langflow/services/tracing/service.py
• src/backend/base/langflow/services/utils.py
• src/backend/base/langflow/template/field/base.py
• src/backend/base/langflow/utils/util.py
• src/backend/base/pyproject.toml
• src/backend/tests/conftest.py
• src/backend/tests/performance/check_key_benchmark.py
• src/backend/tests/unit/api/v1/test_api_key.py
• src/backend/tests/unit/api/v1/test_flows.py
• src/backend/tests/unit/api/v1/test_flows_path_validation.py
• src/backend/tests/unit/api/v1/test_folders.py
• src/backend/tests/unit/test_api_key_source.py
• src/backend/tests/unit/test_database.py
• src/backend/tests/unit/test_get_api_key.py
• src/backend/tests/unit/test_initial_setup.py
• src/frontend/package-lock.json
• src/frontend/package.json
• src/lfx/pyproject.toml
• uv.lock

Purpose and Scope

This document describes the overall system architecture of Langflow, a low-code platform for building AI agents and workflows. It covers the three-tier architecture consisting of the build/deploy layer, backend services, and frontend application, and explains how these layers interact to enable visual flow building and execution.

For specific implementation details about individual subsystems, see:

• Package structure and monorepo organization: 1.3
• Build system and dependency management: 2
• Component system architecture: 3
• Backend services implementation: 4
• Frontend application details: 5

---

High-Level Architecture Overview

Langflow follows a monorepo architecture with three main packages that form distinct architectural layers:

Key architectural characteristics:

Layer	Technology	Purpose
Build & Deploy	uv, npm, Docker	Dependency management, compilation, containerization
Backend Services	FastAPI, SQLModel, LFX	REST API, execution engine, component system
Frontend Application	React, ReactFlow, Zustand	Visual flow editor, state management, user interface

Sources: pyproject.toml1-390 src/backend/base/pyproject.toml1-255 src/frontend/package.json1-173

---

Package Organization

The monorepo is organized as a uv workspace with three core packages:

Package roles:

1. langflow (root): Main package that users install via pip install langflow. Contains minimal dependencies and includes the compiled frontend.

   • Location: pyproject.toml1-390
   • Key dependency: langflow-base[complete]~=0.8.0

2. langflow-base: Core backend functionality including FastAPI application, services, and component system.

   • Location: src/backend/base/pyproject.toml1-255
   • Key dependencies: lfx~=0.3.0, fastapi>=0.115.2, langchain~=0.3.27

3. lfx: Low-level execution engine, component base classes, and graph processing.

   • Location: src/lfx/pyproject.toml (referenced in workspace)
   • Provides core abstractions for components and execution

The workspace configuration is defined in pyproject.toml80-86:

Sources: pyproject.toml1-390 src/backend/base/pyproject.toml1-255

---

Backend Architecture

FastAPI Application Structure

The backend is a FastAPI application that serves both the API and the compiled frontend:

Application initialization sequence (see src/backend/base/langflow/main.py34-135):

1. Lifespan context manager sets up and tears down services
2. create_app() assembles the FastAPI application
3. setup_services() initializes all core services via ServiceManager
4. API routes are registered under /api/v1/*
5. Frontend static files are mounted at / and serve the React application

Key code entities:

• create_app() - src/backend/base/langflow/main.py138-273
• setup_services() - src/backend/base/langflow/main.py276-349
• Service configuration - src/backend/base/langflow/services/

Sources: src/backend/base/langflow/main.py1-800

Service Layer Architecture

The backend uses a service-oriented architecture with centralized service management:

Service lifecycle:

1. Services are registered in ServiceManager
2. Each service implements initialization and teardown
3. Services can depend on other services (e.g., DatabaseService depends on SettingsService)
4. Services are accessed via dependency injection in FastAPI routes

Sources: src/backend/base/langflow/services/ src/backend/base/langflow/main.py276-349

---

Frontend Architecture

React Application Structure

The frontend is a single-page React application built with Vite:

Component hierarchy:

• App.tsx provides routing and global contexts
• PageComponent manages the ReactFlow canvas
• GenericNode represents individual flow components
• Zustand stores manage application state

Sources: src/frontend/src/pages/FlowPage/components/PageComponent/index.tsx1-750 src/frontend/src/CustomNodes/GenericNode/index.tsx1-686

State Management with Zustand

Langflow uses Zustand for centralized state management:

Key store responsibilities:

Store	File	Primary Responsibility
flowStore	src/frontend/src/stores/flowStore.ts1-1000	Manages active flow nodes, edges, and execution state
flowsManagerStore	stores/flowsManagerStore.ts	Manages collection of flows, undo/redo, current flow selection
typesStore	stores/typesStore.ts	Caches component definitions from backend API
alertStore	stores/alertStore.ts	Displays notifications and error messages
messagesStore	stores/messagesStore.ts	Manages chat messages and sessions
globalVariablesStore	stores/globalVariablesStore/	Environment variables and global settings

State synchronization flow:

1. User interacts with ReactFlow canvas
2. ReactFlow events trigger store actions (e.g., onNodesChange)
3. Store updates state and triggers re-renders
4. Changes are persisted via API calls (see autoSaveFlow in src/frontend/src/stores/flowStore.ts86)

Sources: src/frontend/src/stores/flowStore.ts1-1000 src/frontend/src/pages/FlowPage/components/PageComponent/index.tsx1-750

ReactFlow Integration

The visual flow editor is built on ReactFlow (@xyflow/react):

Handle ID format (see src/frontend/src/utils/reactflowUtils.ts323-450):

Handles use escaped JSON strings as IDs to encode type information:

• Target handle (input): {"type":"str","fieldName":"input_value","id":"node_id","inputTypes":["Message","str"]}
• Source handle (output): {"id":"node_id","name":"output","output_types":["Message"],"dataType":"ChatOutput"}

Connection validation (see isValidConnection() at src/frontend/src/utils/reactflowUtils.ts323-450):

1. Parses source and target handle JSON
2. Checks type compatibility between output_types and inputTypes
3. Detects cycles (with special handling for loop components)
4. Validates cardinality (list inputs vs single inputs)

Sources: src/frontend/src/pages/FlowPage/components/PageComponent/index.tsx86-750 src/frontend/src/CustomNodes/GenericNode/index.tsx1-686 src/frontend/src/utils/reactflowUtils.ts1-2000

---

Component System

Component Registry

The component system is based on a JSON registry that catalogs all available components:

Key registry files:

• component_index.json - Complete component catalog with metadata
• stable_hash_history.json - Tracks component code changes for version detection

Component metadata structure (see types in src/frontend/src/types/api/index.ts33-89):

Sources: src/frontend/src/types/api/index.ts1-300

Component Instantiation and Execution Flow

From user interaction to component execution:

Key execution functions:

Function	Location	Purpose
buildFlowVerticesWithFallback()	src/frontend/src/utils/buildUtils.ts	Initiates build with SSE or polling fallback
Graph.from_flow_data()	Backend graph engine	Converts flow JSON to executable DAG
instantiate_class()	Backend component loader	Creates component instances from definitions
Vertex.build()	Backend vertex executor	Executes component with inputs

Event streaming (see src/frontend/src/utils/buildUtils.ts1-800):

• Backend emits events via Server-Sent Events (SSE) at /api/v1/build/{flow_id}/stream
• Frontend listens and updates buildStatus in flowStore
• If SSE fails, falls back to polling at /api/v1/build/{flow_id}/events

Sources: src/frontend/src/utils/buildUtils.ts1-800 src/frontend/src/stores/flowStore.ts1-1000

---

Data Flow Architecture

Complete Request-Response Flow

Data transformation stages:

1. User Interaction → ReactFlow State

   • User modifies node parameters in GenericNode
   • GenericNode calls store actions to update nodes array
   • ReactFlow re-renders affected nodes

2. ReactFlow State → Backend Format

   • flowStore serializes nodes/edges to flow JSON
   • Helper functions in reactflowUtils.ts transform ReactFlow objects
   • API client sends to /api/v1/flows/{id} or /api/v1/build/{id}/flow

3. Backend Processing

   • FastAPI receives flow JSON
   • Graph class converts JSON to executable DAG
   • Vertex instances execute components in topological order

4. Backend Results → Frontend Display

   • Backend emits progress events via SSE
   • Frontend updates buildStatus map in flowStore
   • GenericNode components display status indicators
   • Results shown in output panels or chat interface

Sources: src/frontend/src/CustomNodes/GenericNode/index.tsx1-686 src/frontend/src/utils/reactflowUtils.ts1-2000 src/frontend/src/utils/buildUtils.ts1-800

---

Build System and Development Workflow

Development Environment Setup

The project uses uv for Python dependency management and npm for frontend builds:

Key development workflows:

Command	Purpose	Details
make init	First-time setup	Installs all dependencies (backend + frontend)
make run_cli	Run Langflow	Builds frontend, then starts backend server
make backend	Backend only	Starts FastAPI without rebuilding frontend
make frontend	Frontend only	Starts Vite dev server on port 3000
make format	Format code	Runs Ruff (Python) and Biome (TypeScript)

Hot-reload component development (see Makefile290-298):

• Enables dynamic component loading without rebuilding
• Components are reloaded from source on each request

Sources: Makefile1-600

Build and Deployment Pipeline

Build commands (see Makefile407-466):

Docker images (multiple variants available):

• langflowai/langflow:latest - Full application
• langflowai/langflow-backend:latest - Backend only
• langflowai/langflow-frontend:latest - Frontend only

Sources: Makefile407-466

---

Technology Stack Summary

Layer	Core Technologies	Key Libraries
Backend	Python 3.10-3.13, FastAPI, SQLModel	langchain, pydantic, alembic, uvicorn
Frontend	React 19, TypeScript, Vite	@xyflow/react, zustand, axios, tailwindcss
Execution	LFX engine, Python async	langchain-core, networkx, diskcache
Build	uv, npm, Docker	hatch, vite, Biome, Ruff
Database	SQLite (default), PostgreSQL	sqlalchemy, asyncio, alembic
Testing	pytest, Playwright	pytest-asyncio, jest, pytest-xdist

Browser compatibility:

• Modern browsers with ES2020+ support
• ReactFlow requires canvas and WebGL
• WebSocket support for real-time features

Python compatibility:

• Requires Python >=3.10, <3.14 (see pyproject.toml5)
• Uses async/await extensively
• Type hints throughout (mypy checked)

Sources: pyproject.toml1-390 src/backend/base/pyproject.toml1-255 src/frontend/package.json1-173