# langflow-ai/langflow — codebase unpack

> Canonical page: https://codevetter.com/unpack/langflow

This is a deterministic Repo Unpack scan of langflow-ai/langflow — a structural map, not a review, security audit, or maintainer-endorsed description.

- Scanned commit: 5621dcfd84e11108e4cc1ecb0c51f41053c4211c (2026-09-15)
- Last upstream commit: chore: merge release-1.12.2 into main
- Generated by codevetter 1.12.0 on 2026-09-22
- 3997 files scanned · 32.9 MB

## Languages

- Python: 4077 files
- TypeScript: 2523 files
- Markdown: 1514 files
- JavaScript: 656 files
- Shell: 449 files
- JSON: 389 files
- YAML: 83 files
- TOML: 29 files

## Repository structure

- docs/ — 1862 files
- src/ — 1858 files
- scripts/ — 103 files
- .github/ — 63 files
- .agents/ — 37 files
- docker/ — 17 files
- deploy/ — 13 files
- regressions/ — 5 files

Probable source entrypoint: `src/` (inferred from the tree, not upstream docs)

## Package

- package.json: null — 1 declared dependencies

## Structural health signals

Average score 7.5/10 across 96 files; 14 hotspots. These are deterministic review leads, not proof of a bug.

## Recent history

- 5621dcfd84e1 (2026-09-15) chore: merge release-1.12.2 into main
- c979695ce660 (2026-09-15) fix(jobs): atomically claim expired HITL pauses (#15096)
- 5cb970863e6c (2026-09-15) fix(lfx): close temp file before deleting failed cloud downloads (#15074)
- 999fc3583d68 (2026-09-14) fix: warn when restricted workflows substitute saved component code (#15090)
- 2029e8f772d4 (2026-09-14) fix: allow concurrent flow version attachments on PostgreSQL (#15086)

## Overview

Langflow is a visual builder and runtime for AI/LLM workflows (agents, RAG pipelines, tool chains): users compose 'components' into a flow graph on a React canvas, persist the graph as JSON in a database, and execute it through a FastAPI backend that compiles the payload into a vertex graph and runs it against a pluggable component catalog. The repo is a uv monorepo split into lfx (headless executor, shared primitives, built-in components, its own `lfx`/`lfx-mcp` CLIs), langflow-base (the FastAPI app, service layer, auth, SQLModel/Alembic persistence), the curated `langflow` distribution that adds lfx-* provider bundles, a React 19 + Vite frontend, and a `langflow-sdk` Python client. Its distinctive shape is a heavily-pluginized service layer: auth, authorization, catalog/model-provider policy and even routes are replaceable through entry points and lfx.toml config.

## System map

Langflow ships as a uv workspace whose public dependency direction is langflow -> langflow-base -> lfx, plus ~24 lfx-* provider bundle packages and a React/Vite frontend. The primary entrypoint is the `langflow` console script (langflow_launcher -> Typer app in __main__.py -> `langflow run`), which boots a FastAPI app created by create_app() in main.py and served by gunicorn on Linux or direct uvicorn on Windows/macOS. All cross-cutting capabilities (auth, DB, cache, storage, telemetry, tracing, job queue, ...) live behind a singleton ServiceManager in lfx with factory registration plus entry-point/config-file plugin discovery. Persistence is SQLAlchemy 2 async + SQLModel (aiosqlite default, Postgres supported) migrated by Alembic. The graph execution engine (Graph, Vertex, Edge) lives in lfx and is shared by the server and the standalone `lfx run`/`lfx serve` CLIs.
- The `langflow` console script resolves to langflow.langflow_launcher:main; on Darwin it re-execs `python -m langflow.__main__` after setting OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES because Objective-C fork-safety would otherwise SIGSEGV gunicorn workers. — [src/backend/base/pyproject.toml#L447-448](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/pyproject.toml#L447-L448) [src/backend/base/langflow/langflow_launcher.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/langflow_launcher.py)
- `langflow.__main__` is a Typer app exposing commands run, superuser, api_key, copy_db, migration, migrate-mcp, reconcile-kb-from-disk; it mounts an `lfx` sub-app (serve/run) and an `observability` group from lfx.cli. — [src/backend/base/langflow/__main__.py#L66-95](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L66-L95) [src/backend/base/langflow/__main__.py#L401](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L401) [src/backend/base/langflow/__main__.py#L950-1210](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L950-L1210)
- create_app() in main.py builds the FastAPI app: ContentSizeLimit + Sentry + CORS middleware, JavaScriptMIMEType fix, an execution-client header binder, a multipart-boundary validator for /api/v1/files/upload, X-Forwarded-Prefix handling, comma-flattened query strings, and Accept-Language locale resolution; it mounts router (/api/v1, /api/v2), health_check_router, log_router, then plugin routes. — [src/backend/base/langflow/main.py#L854-1155](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L854-L1155) [src/backend/base/langflow/api/router.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/router.py) [src/backend/base/langflow/middleware.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/middleware.py)
- The uv workspace members are src/backend/base (langflow-base), the root (langflow), src/lfx, src/langflow-stepflow, src/sdk, and ~24 src/bundles/* packages; the curated distribution declares bounded ranges for lfx-* bundles (e.g. lfx-openai>=0.1.4,<1.0.0) while lfx-bundles stays opt-in. — [pyproject.toml#L130-163](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L130-L163) [pyproject.toml#L19-46](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L19-L46)
- The documented package layering is frontend ->HTTP-> langflow-base -> lfx -> langchain-core/pydantic, with lfx forbidden from importing langflow.* and vendor components living only in src/bundles/<provider> packages. — [docs/agents/ARCHITECTURE.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/docs/agents/ARCHITECTURE.md) [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md)
- All services hang off a singleton ServiceManager (lfx/services/manager.py) created lazily via get_service_manager(); register_all_service_factories() in langflow/services/utils.py registers ~25 factories (settings, cache, chat, database, session, storage, variable, telemetry, tracing, transaction, state, checkpoint, job_queue, task, store, shared_component_cache, auth, authorization, policy_bundle, catalog_policy, model_provider_policy, mcp_composer, executor). — [src/lfx/src/lfx/services/manager.py#L43-60](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/services/manager.py#L43-L60) [src/backend/base/langflow/services/utils.py#L561-647](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/utils.py#L561-L647)
- langflow/services/deps.py exposes typed getters (get_db_service, get_auth_service, get_queue_service, ...) and the canonical async session_scope() context manager; get_session is deprecated and raises NotImplementedError. get_auth_service() defensively swaps out lfx's no-op AuthService stub for Langflow's JWT implementation. — [src/backend/base/langflow/services/deps.py#L158-181](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/deps.py#L158-L181) [src/backend/base/langflow/services/deps.py#L254-293](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/deps.py#L254-L293)
- Persistence is SQLModel/SQLAlchemy async (aiosqlite default via LANGFLOW_DATABASE_URL=sqlite:///./langflow.db, Postgres via postgresql://) with Alembic migrations in langflow/alembic; a Postgres advisory lock (0x4C616E67666C6F77) serializes concurrent `alembic upgrade` across workers. — [src/backend/base/langflow/services/database/service.py#L1-70](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/database/service.py#L1-L70) [.env.example#L20-23](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.env.example#L20-L23) [src/backend/base/langflow/services/database/models/flow/model.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/database/models/flow/model.py)
- The execution engine is lfx.graph.graph.base.Graph (~3.2k lines) with from_payload(), arun(), async_start(), build_vertex(), prepare(), RunnableVerticesManager, checkpoint support (GraphCheckpoint), OTel `flow.execute` spans, and per-run state (run_id, session_id, end_user_id, persist_messages). — [src/lfx/src/lfx/graph/graph/base.py#L126-200](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/graph/graph/base.py#L126-L200) [src/lfx/src/lfx/graph/graph/base.py#L495](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/graph/graph/base.py#L495)
- The frontend is React 19 + TypeScript + Vite + Zustand stores (flowStore, authStore, ...) + @xyflow/react canvas, packaged as `langflow` v1.12.2 in src/frontend/package.json; the built SPA is served by the backend via setup_static_files() which reserves /api GET/HEAD to return JSON 404s instead of the SPA shell. — [src/frontend/package.json](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/frontend/package.json) [src/frontend/src/stores/flowStore.ts](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/frontend/src/stores/flowStore.ts) [src/backend/base/langflow/main.py#L1182-1199](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L1182-L1199)
- Deployment shape: `langflow run` uses gunicorn multi-worker fork on Linux and direct uvicorn (clamped to 1 worker) on Windows/macOS; ensure_multi_worker_safe() refuses to boot with >1 worker on the default in-memory job queue unless LANGFLOW_JOB_QUEUE_TYPE=redis or LANGFLOW_DANGEROUSLY_ALLOW_MULTI_WORKER_WITHOUT_SHARED_QUEUE=true. — [src/backend/base/langflow/__main__.py#L169-198](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L169-L198) [src/backend/base/langflow/__main__.py#L291-348](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L291-L348)
- Observability is wired through lfx.observability: instrument_fastapi_app(app), execution_client/execution_protocol contextvars, an event-loop lag monitor, DB pool metrics, a Prometheus HTTP server gated by LANGFLOW_PROMETHEUS_PORT, and optional sentry_sdk init from LANGFLOW_SENTRY_DSN inside the lifespan. — [src/backend/base/langflow/main.py#L25-31](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L25-L31) [src/backend/base/langflow/main.py#L231-249](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L231-L249) [src/backend/base/langflow/main.py#L370-391](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L370-L391) [src/backend/base/langflow/services/telemetry/opentelemetry.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/telemetry/opentelemetry.py)
- Build/dev commands are Makefile-driven: `make init` (uv sync --frozen --extra postgresql + npm + pre-commit), `make backend`/`make frontend` dev servers, `make unit_tests`, `make lint` (mypy); Python tooling uses ruff with select=ALL at line-length 120 and a large per-file-ignores table codifying intentional violations. — [Makefile](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/Makefile) [pyproject.toml#L347-395](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L347-L395)

## Feature catalog

The v1 API (~35 routers under /api/v1) covers flow CRUD and sharing, graph build/run (job-queue + SSE), webhooks, files, variables, users/API keys, folders/projects, knowledge bases, memories, monitor/traces, a Langflow Store client, voice mode, A2A, an OpenAI-compatible responses route, MCP servers (global and per-project), and a full authz administration surface (shares, roles, assignments, teams, audit, me). v2 under /api/v2 hosts the workflow execution contract (sync/stream/background runs via a shared lfx router bound to a Langflow host), v2 files/MCP, and registration. Beyond HTTP there is the `lfx` executor CLI (run/serve a flow without the DB), `lfx-mcp`, a Python SDK, and a feature-gated 'agentic experience' with its own routers.
- Flow management: api/v1/flows.py implements POST/GET/PATCH/PUT upsert/DELETE plus batch create, upload/download of flow JSON, basic_examples, and a note_translations + expand_compact_flow endpoint; flow rows carry name, data JSON, endpoint_name, webhook/mcp_enabled flags, access_type PRIVATE|PUBLIC, folder/workspace scoping. — [src/backend/base/langflow/api/v1/flows.py#L289-490](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/flows.py#L289-L490) [src/backend/base/langflow/services/database/models/flow/model.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/database/models/flow/model.py)
- Synchronous and streaming flow execution: POST /api/v1/run/{flow_id_or_name} (and a session-scoped variant) plus POST /api/v1/webhook/{flow_id_or_name} with an SSE webhook-events stream; all funnel through _run_flow_internal -> simple_run_flow. — [src/backend/base/langflow/api/v1/endpoints.py#L1082-1151](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L1082-L1151) [src/backend/base/langflow/api/v1/endpoints.py#L1236-1330](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L1236-L1330) [src/backend/base/langflow/api/v1/endpoints.py#L884-1050](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L884-L1050)
- Editor build pipeline: POST /api/v1/build/{flow_id}/flow returns a job_id; GET /api/v1/build/{job_id}/events polls SSE (or event_delivery=direct streams inline); plus cancel_build, deprecated vertex-order/vertex-build endpoints, and public unauthenticated variants build_public_tmp. — [src/backend/base/langflow/api/v1/chat.py#L304-477](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/chat.py#L304-L477) [src/backend/base/langflow/api/v1/chat.py#L479-545](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/chat.py#L479-L545) [src/backend/base/langflow/api/v1/chat.py#L995-1299](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/chat.py#L995-L1299)
- v2 workflow API: POST /api/v2/workflows is owned by the shared lfx.workflow.router.create_workflow_router bound to LangflowWorkflowHost, which supplies resolve_caller (session cookie/API key), get_flow (share-aware fetch), authorize (WorkflowAction->FlowAction), run_sync, stream_response, and submit_background; langflow keeps its own GET status/POST stop/GET events durable routes. — [src/backend/base/langflow/api/router.py#L141-164](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/router.py#L141-L164) [src/backend/base/langflow/api/v2/workflow_host.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v2/workflow_host.py) [src/backend/base/langflow/api/v2/workflow_background.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v2/workflow_background.py)
- MCP integration is bidirectional: api/v1/mcp.py runs an MCP server exposing flows as tools over SSE (SseServerTransport) and Streamable HTTP (StreamableHTTPSessionManager, started in the lifespan), api/v1/mcp_projects.py runs per-project MCP servers, and an MCPComposerService plus an agentic MCP router exist; client-side MCP sessions are pooled by MCPSessionManager tunables. — [src/backend/base/langflow/api/v1/mcp.py#L1-60](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/mcp.py#L1-L60) [src/backend/base/langflow/api/v1/mcp.py#L147-326](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/mcp.py#L147-L326) [src/backend/base/langflow/api/v1/mcp_projects.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/mcp_projects.py) [.env.example#L185-204](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.env.example#L185-L204)
- Authentication surface: POST /api/v1/login (OAuth2 password form -> JWT access+refresh), GET /auto_login, POST /refresh, /logout, users CRUD, api_key CRUD; API-key auth is via x-api-key header/query validated against DB keys or a single LANGFLOW_API_KEY when LANGFLOW_API_KEY_SOURCE=env. — [src/backend/base/langflow/api/v1/login.py#L34-249](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/login.py#L34-L249) [.env.example#L118-131](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.env.example#L118-L131) [src/backend/tests/unit/test_api_key_source.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/tests/unit/test_api_key_source.py)
- RBAC/authorization administration: /api/v1/authz/* routers (shares CRUD with an OSS owner floor, roles, role assignments, teams, me, and a superuser-only audit query capped at 200/page) sit behind guards in services/authorization; the feature is off by default (LANGFLOW_AUTHZ_ENABLED=false) with an OSS pass-through service. — [src/backend/base/langflow/api/router.py#L101-106](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/router.py#L101-L106) [src/backend/base/langflow/api/v1/authz_shares.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/authz_shares.py) [src/backend/base/langflow/api/v1/authz_audit.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/authz_audit.py) [src/backend/base/langflow/services/authorization/guards.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/authorization/guards.py)
- File handling: /api/v1/files upload/download (multipart boundary validated by middleware) and v2 files; the StorageService abstracts local disk vs S3 (services/storage/local.py, s3.py). — [src/backend/base/langflow/api/v1/files.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/files.py) [src/backend/base/langflow/main.py#L924-957](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L924-L957) [src/backend/base/langflow/services/storage/s3.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/storage/s3.py)
- Governance/policy surfaces: model_provider_policy, catalog_policy, policy_bundle routers administer which providers/components a project may use; a model_provider_policy_refresh_worker runs per worker at startup. — [src/backend/base/langflow/api/router.py#L99-107](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/router.py#L99-L107) [src/backend/base/langflow/services/model_provider_policy.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/model_provider_policy.py) [src/backend/base/langflow/services/task/model_provider_policy_refresh.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/task/model_provider_policy_refresh.py)
- Interoperability endpoints: voice_mode router (voice), a2a.py (agent-to-agent protocol, gated per-request by LANGFLOW_A2A_ENABLED), openai_responses.py (OpenAI-compatible /responses), and a store.py client to api.langflow.store for sharing components. — [src/backend/base/langflow/api/v1/voice_mode.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/voice_mode.py) [src/backend/base/langflow/api/v1/a2a.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/a2a.py) [src/backend/base/langflow/api/v1/openai_responses.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/openai_responses.py) [src/backend/base/langflow/api/v1/store.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/store.py)
- Feature-gated 'agentic experience': _include_agentic_router() mounts agentic_router plus files/sessions routers behind require_agentic_experience and an agentic MCP router; sandbox-management endpoints share the gate while /agentic/check-config stays readable. — [src/backend/base/langflow/api/router.py#L117-135](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/router.py#L117-L135) [src/backend/base/langflow/agentic/api/router.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/agentic/api/router.py)
- lfx CLI is a standalone Typer app (`lfx`, plus `lfx-mcp`) with registered command groups: setup, observability, prewarm, authoring, upgrade, extension, running (`lfx run`, `lfx serve` which serves flow JSON/Python scripts as an HTTP API via a FlowRegistry), and remote. — [src/lfx/src/lfx/__main__.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/__main__.py) [src/lfx/src/lfx/cli/_running_commands.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/cli/_running_commands.py) [src/lfx/src/lfx/cli/commands.py#L261-340](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/cli/commands.py#L261-L340) [src/lfx/pyproject.toml#L114-116](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/pyproject.toml#L114-L116)
- Component catalog: ~108 component subdirectories under src/lfx/src/lfx/components (providers, vectorstores, embeddings, tools, agents, io, ...) plus curated lfx-* bundles under src/bundles (openai, anthropic, amazon, google, datastax, docling, ...) that ship extension.json manifests. — [src/lfx/src/lfx/components](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/components) [src/bundles/openai/pyproject.toml#L36-50](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/bundles/openai/pyproject.toml#L36-L50)
- langflow-sdk is a separate workspace package (src/sdk) shipping a typed Python client with sync/async clients, background-job polling, environments, and pytest helpers for testing against a Langflow server. — [src/sdk/src/langflow_sdk/client.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/sdk/src/langflow_sdk/client.py) [src/sdk/src/langflow_sdk/_async_client.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/sdk/src/langflow_sdk/_async_client.py) [src/sdk/pyproject.toml](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/sdk/pyproject.toml)

## Data flow

The core data path is: flow JSON (nodes+edges) persisted in the `flow` SQLModel table -> loaded owner-scoped or share-aware -> optionally sanitized by caller-aware component policy -> tweaks applied -> Graph.from_payload compiles vertices/edges -> graph.arun executes vertices and emits events -> RunResponse/SSE to the caller while messages, transactions, and vertex_builds rows persist execution history. Secrets (global variables, API keys) are Fernet-encrypted at rest using LANGFLOW_SECRET_KEY. Files go through a local/S3 StorageService namespaced per flow. Components themselves are discovered at boot from built-ins, components_path dirs, extension bundles, and remote bundle URLs, and cached in component_cache.
- Flow persistence: Flow rows store the graph as `data` JSON (nodes/edges/viewport) with name/endpoint_name/access_type/webhook/mcp_enabled metadata; cascade_delete_flow manually deletes MessageTable, TransactionTable, VertexBuildTable, FlowVersion, SpanTable/TraceTable, AuthzShare and the Flow row because SQLite FK cascades are not guaranteed. — [src/backend/base/langflow/services/database/models/flow/model.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/database/models/flow/model.py) [src/backend/base/langflow/api/utils/flow_utils.py#L103-141](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/utils/flow_utils.py#L103-L141)
- Graph materialization: simple_run_flow loads flow.data, applies caller-aware component policy (prepare_flow_build_for_user), then either serves a warm-registry template (try_warm_run_graph) or runs process_tweaks + apply_global_variable_defaults + Graph.from_payload(payload, flow_id, user_id, context). — [src/backend/base/langflow/api/v1/endpoints.py#L382-452](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L382-L452) [src/lfx/src/lfx/graph/graph/base.py#L1777](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/graph/graph/base.py#L1777)
- Tweaks and targeted inputs mutate the graph payload pre-instantiation via lfx.processing.process.process_tweaks/validate_targeted_inputs; refused tweaks raise TweakRefusedError mapped to a structured 422 (code TWEAKS_REFUSED) by an app-level handler, and non-owners are blocked from tweaking stored flows by _enforce_owner_only_tweaks. — [src/lfx/src/lfx/processing/process.py#L48-60](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/processing/process.py#L48-L60) [src/backend/base/langflow/main.py#L1047-1066](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L1047-L1066) [src/backend/base/langflow/api/v1/endpoints.py#L136-146](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L136-L146)
- Execution: run_graph_internal sets graph.session_id then awaits graph.arun(inputs..., outputs, stream, event_manager); results return as list[RunOutputs] -> RunResponse; v1 responses and SSE frames re-project content_blocks via project_payload_to_v1 to keep the 1.11 wire shape. — [src/lfx/src/lfx/processing/process.py#L62-108](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/processing/process.py#L62-L108) [src/backend/base/langflow/api/v1/endpoints.py#L682-709](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L682-L709)
- Streaming events: build/run events are produced into an asyncio.Queue owned by JobQueueService.create_queue(job_id) and consumed by get_build_events/consume_and_yield; a RedisJobQueueService backend (LANGFLOW_JOB_QUEUE_TYPE=redis) shares queues across gunicorn workers and is connectivity-probed at startup. — [src/backend/base/langflow/services/job_queue/service.py#L22-50](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/job_queue/service.py#L22-L50) [src/backend/base/langflow/services/utils.py#L716-731](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/utils.py#L716-L731) [src/backend/base/langflow/api/v1/endpoints.py#L712-745](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L712-L745)
- Credential storage: DatabaseVariableService stores global variables; CREDENTIAL_TYPE values are Fernet-encrypted/decrypted via auth service helpers keyed on LANGFLOW_SECRET_KEY — short secrets derive the key with SHA-256, and a MultiFernet retains a legacy PRNG-derived key for decrypting pre-1.10.1 ciphertext. — [src/backend/base/langflow/services/variable/service.py#L27-38](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/variable/service.py#L27-L38) [src/backend/base/langflow/services/auth/utils.py#L416-480](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/auth/utils.py#L416-L480)
- File inputs for public flows are restricted to the `{source_flow_id}/{basename}` namespace by validate_public_files (mitigation for GHSA-rcjh-r59h-gq37), and session IDs for anonymous public runs are namespaced per (client_id, flow_id) by scope_session_to_namespace / compute_virtual_flow_id (CVE-2026-33017). — [src/backend/base/langflow/api/utils/flow_utils.py#L144-218](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/utils/flow_utils.py#L144-L218)
- Component discovery at boot: lifespan calls get_and_cache_all_types_dict (lfx.interface.components) which merges built-in lfx components, settings.components_path directories, extension components (import_extension_components over DiscoveredExtension records), and bundles downloaded from settings.bundle_urls into temp dirs by load_bundles_from_urls. — [src/backend/base/langflow/main.py#L395-428](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L395-L428) [src/lfx/src/lfx/interface/components.py#L1128-1191](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/interface/components.py#L1128-L1191) [src/backend/base/langflow/initial_setup/setup.py#L1103-1146](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/initial_setup/setup.py#L1103-L1146)
- Execution history is persisted per run: JobService.create_job writes a WORKFLOW job row, vertex builds and transactions land in VertexBuildTable/TransactionTable, and startup cleanup prunes both tables plus authz_audit_log to configured retention (max_transactions_to_keep, max_vertex_builds_to_keep, AUTHZ_AUDIT_RETENTION_DAYS). — [src/backend/base/langflow/api/v1/endpoints.py#L505-539](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L505-L539) [src/backend/base/langflow/services/utils.py#L464-558](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/utils.py#L464-L558) [src/backend/base/langflow/services/jobs/factory.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/jobs/factory.py)
- Per-request identity context: session cookie/API-key auth resolves through get_current_user_for_workflow/api_key_security; a serving-plane end-user header is merged into the effective session_id by resolve_serving_scope and stamped on graph.end_user_id while execution still runs as flow.user_id; execution_client/execution_protocol contextvars label the surface for tracing. — [src/backend/base/langflow/api/v1/endpoints.py#L453-481](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L453-L481) [src/backend/base/langflow/api/v2/workflow_host.py#L50-69](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v2/workflow_host.py#L50-L69) [src/lfx/src/lfx/graph/graph/base.py#L173-195](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/graph/graph/base.py#L173-L195)
- Durable/background runs: POST /api/v2/workflows mode=background dispatches to LangflowWorkflowHost.submit_background -> submit_background_with_mapping, with HITL pause/resume supported by a CheckpointService (lfx.graph.checkpoint CheckpointStore) and orphan sweeping on startup via background_execution service. — [src/backend/base/langflow/api/v2/workflow_host.py#L126-136](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v2/workflow_host.py#L126-L136) [src/backend/base/langflow/api/v2/hitl.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v2/hitl.py) [src/backend/base/langflow/main.py#L545-549](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L545-L549) [docs/features/durable-execution-hitl.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/docs/features/durable-execution-hitl.md)
- Outbound calls a boot makes: models.dev catalog refresh (daily task, disabled by LANGFLOW_MODELS_DEV_REFRESH=false), bundle URL fetches, store webhooks (LANGFLOW_DOWNLOAD_WEBHOOK_URL/LIKE_WEBHOOK_URL), GitHub archive downloads via detect_github_url, and version checks via fetch_latest_version. — [src/backend/base/langflow/main.py#L581-632](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L581-L632) [src/backend/base/langflow/initial_setup/setup.py#L1072-1100](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/initial_setup/setup.py#L1072-L1100) [.env.example#L206-217](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.env.example#L206-L217) [src/backend/base/langflow/__main__.py#L63](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L63)

## Behavior traces

Traced end-to-end: (1) `langflow run` startup from console script through lifespan service init; (2) a synchronous POST /api/v1/run/{flow} execution; (3) the editor's build+events flow; (4) flow deletion cascade; (5) v2 workflow dispatch; (6) shutdown ordering. Each hop below names the actual functions in call order.
- Startup trace: `langflow` script -> langflow_launcher.main (Darwin re-exec for OBJC fork safety) -> typer `run` command -> env-file load -> production preflight + Postgres version check -> ProcessManager spawns gunicorn (Linux) or uvicorn (win/mac, workers clamped to 1) -> create_app() -> get_lifespan(). — [src/backend/base/langflow/langflow_launcher.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/langflow_launcher.py) [src/backend/base/langflow/__main__.py#L13-20](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L13-L20) [src/backend/base/langflow/__main__.py#L162-198](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L162-L198) [src/backend/base/langflow/main.py#L854-869](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L854-L869)
- Lifespan init order: configure() logging -> optional sentry_sdk.init -> ensure_production_preflight -> initialize_services (register_all_service_factories -> initialize_database + alembic -> hydrate_policy_bundle -> hydrate_catalog_policy -> setup_superuser -> clean_transactions/vertex_builds/authz_audit_log) -> initialize_environment_variables -> telemetry writer + audit_cleanup + model_provider_policy_refresh workers -> setup_llm_caching -> profile pictures -> KB/memory-base backfills -> Prometheus -> load_bundles_from_urls -> get_and_cache_all_types_dict -> create_or_update_starter_projects (FileLock) -> agentic globals -> telemetry_service.start -> MCPComposerService.start -> MCP server backfill -> load_flows_from_directory -> warm registry task -> sync_flows_from_fs + queue_service.start -> orphan sweep -> delayed init_mcp_servers -> streamable-HTTP managers -> lag monitor + DB pool instrumentation -> enterprise hooks. — [src/backend/base/langflow/main.py#L192-661](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L192-L661) [src/backend/base/langflow/services/utils.py#L699-757](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/utils.py#L699-L757)
- Superuser bootstrap: setup_superuser branches on AUTO_LOGIN — when on, it ignores a legacy default password, generates token_urlsafe(32), takes a FileLock (langflow_auto_login_superuser.lock), creates the user via auth.create_super_user, initializes variables and the default folder; when off, it requires configured credentials and deletes an unused default superuser on teardown. — [src/backend/base/langflow/services/utils.py#L141-263](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/utils.py#L141-L263) [src/backend/base/langflow/services/utils.py#L402-425](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/utils.py#L402-L425)
- Sync run trace: POST /api/v1/run/{flow_id_or_name} -> api_key_security / get_current_user -> get_flow_by_id_or_endpoint_name (widen_for_shares) -> ensure_flow_permission(EXECUTE) -> _run_flow_internal -> _enforce_owner_only_tweaks -> resolve_serving_scope -> simple_run_flow -> set_current_model_provider_policy_context -> prepare_flow_build_for_user -> try_warm_run_graph or (process_tweaks -> raise_if_hitl_unsupported -> apply_global_variable_defaults -> Graph.from_payload) -> graph.set_run_id -> JobService.create_job + execute_with_status -> run_graph_internal -> graph.arun -> RunResponse -> _v1_run_response (content_blocks projection). — [src/backend/base/langflow/api/v1/endpoints.py#L807-1050](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L807-L1050) [src/backend/base/langflow/api/v1/endpoints.py#L382-577](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L382-L577) [src/lfx/src/lfx/processing/process.py#L62-108](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/processing/process.py#L62-L108)
- Streaming run trace: _run_flow_internal(stream=True) creates an asyncio.Queue + client_consumed_queue, wraps them in a tokens EventManager, spawns run_flow_generator as a task (simple_run_flow(stream=True) -> event_manager.on_end/on_error -> sentinel None), and returns StreamingResponse(consume_and_yield(...)) with an on_disconnect cancel. — [src/backend/base/langflow/api/v1/endpoints.py#L747-805](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L747-L805) [src/backend/base/langflow/api/v1/endpoints.py#L961-986](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L961-L986)
- Editor build trace: POST /api/v1/build/{flow_id}/flow -> session_scope _read_flow (owner-scoped, PUBLIC fallback) -> ensure_flow_permission(EXECUTE) with deny->404 reframe unless READ passes -> resolve_flow_data_override drops caller data unless flow:write -> prepare_flow_build_for_user sanitizes stored/inline data -> start_flow_build -> validate_targeted_inputs -> queue_service.create_queue(job_id) -> generate_flow_events task (build_graph_from_db/build_graph_from_data -> graph.prepare -> per-vertex build emits VertexBuildResponse events) -> returns {job_id} -> client polls GET /build/{job_id}/events -> _register_job_owner_or_cancel records ownership for cancel. — [src/backend/base/langflow/api/v1/chat.py#L304-477](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/chat.py#L304-L477) [src/backend/base/langflow/api/build.py#L185-250](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/build.py#L185-L250) [src/backend/base/langflow/api/utils/flow_utils.py#L47-100](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/utils/flow_utils.py#L47-L100)
- Flow deletion trace: DELETE /api/v1/flows/{flow_id} -> owner/authz check -> cascade_delete_flow -> check_flow_has_deployed_versions guard -> delete messages -> transactions -> vertex_builds -> flow_versions -> spans then traces (FK order) -> authz_share rows -> flow row; rowcount==1 verifies removal. — [src/backend/base/langflow/api/v1/flows.py#L921-979](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/flows.py#L921-L979) [src/backend/base/langflow/api/utils/flow_utils.py#L103-141](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/utils/flow_utils.py#L103-L141)
- v2 workflow trace: POST /api/v2/workflows -> lfx create_workflow_router -> LangflowWorkflowHost.resolve_caller (oauth2_login cookie -> api_key query -> header -> get_current_user_for_workflow, in its own session_scope to avoid SQLite contention) -> get_flow (resolve_flow_for_execution) -> authorize (authorize_flow_action, deny->404) -> branch: run_sync_with_mapping (job-tracked), build_stream_response (v1 build-vertex loop + AG-UI), or submit_background_with_mapping (durable). — [src/backend/base/langflow/api/router.py#L141-164](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/router.py#L141-L164) [src/backend/base/langflow/api/v2/workflow_host.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v2/workflow_host.py) [src/lfx/src/lfx/workflow/router.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/workflow/router.py)
- Service resolution trace: get_service(ServiceType.X) -> ServiceManager.get (keyed lock) -> first-call discover_plugins (entry points `lfx.services` override=False, then lfx.toml/pyproject `[tool.lfx.services]` override=True) -> service_classes direct registration wins -> _create_service_from_class inspects __init__ params and recursively resolves ServiceType dependencies -> otherwise _create_service_from_factory resolves factory.dependencies then factory.create() + set_ready(). — [src/backend/base/langflow/services/deps.py#L38-60](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/deps.py#L38-L60) [src/lfx/src/lfx/services/manager.py#L121-269](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/services/manager.py#L121-L269) [src/lfx/src/lfx/services/manager.py#L366-558](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/services/manager.py#L366-L558)
- Shutdown trace: lifespan finally -> cleanup_mcp_sessions FIRST (kill MCP subprocesses) -> enterprise shutdown hooks -> stop_event_loop_lag_monitor -> staged progress (stop server -> cancel sync_flows_from_fs/mcp_init/models_dev/warm_registry tasks + stop streamable-HTTP/project/agentic MCP managers + A2A push client + audit/policy workers) -> drain_pending_audit_writes -> teardown_services (30s cap; teardown_superuser deletes unused default superuser when AUTO_LOGIN off) -> shutdown_sandbox (QEMU guests) -> temp_dir cleanup -> summary. — [src/backend/base/langflow/main.py#L694-849](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L694-L849) [src/backend/base/langflow/services/utils.py#L428-436](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/utils.py#L428-L436)

## Testing signals

Backend tests are pytest with asyncio_mode=auto across three roots (src/backend/tests ~778 files, src/lfx/tests ~425, src/bundles/*/tests ~76), with a rich marker taxonomy and heavyweight plugins (blockbuster for blocking-call detection, pytest-timeout in thread/faulthandler mode, xdist, rerunfailures, flakefinder, hypothesis, pyleak). The conftest boots the real app via create_app/LifespanManager over ASGITransport and StaticPool SQLite. Frontend uses Jest unit tests plus Playwright e2e (a11y/core/extended/live suites) with merged nyc coverage. CI runs a Python matrix (3.10/3.14) with split groups, bundle-guarded jobs, template tests, docker tests, CodeQL, and DB-migration validation.
- pytest is configured at the repo root: testpaths = src/backend/tests, src/lfx/tests, src/bundles/*/tests; asyncio_mode=auto; per-test timeout=90s with timeout_method=thread (temporary diagnostic for a Group-3 hang that dumps all thread stacks); addopts disables the benchmark plugin. — [pyproject.toml#L279-312](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L279-L312)
- Markers declared: async_test, api_key_required (deselected in CI via `-m "not api_key_required"` — those tests hit live provider APIs), no_blockbuster, benchmark, unit, integration, slow, security (IDOR/auth/access-control regression), real_services (needs real SQLite+Postgres+Redis). — [pyproject.toml#L299-309](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L299-L309) [.github/workflows/python_test.yml#L176-180](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.github/workflows/python_test.yml#L176-L180)
- Dev-group test tooling is extensive: blockbuster (blocking-call detection in async), pytest-xdist/-sugar/-instafail/-cov/-split/-flakefinder/-rerunfailures/-timeout/-profiling, respx (httpx mocks), hypothesis, pyleak (leak detection), locust (load), fakeredis, codeflash, and mcp-server-fetch. — [pyproject.toml#L50-89](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L50-L89)
- The backend conftest builds a real app: TestClient/AsyncClient over ASGITransport + asgi-lifespan LifespanManager around create_app(), a StaticPool async engine for SQLite, blockbuster_ctx, and api-key fixtures; tests are instructed to prefer real integrations over mocks. — [src/backend/tests/conftest.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/tests/conftest.py) [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md)
- Component tests have dedicated base classes (ComponentTestBaseWithClient / ComponentTestBaseWithoutClient) requiring component_class, default_kwargs, file_names_mapping fixtures, living under src/backend/tests/unit/components. — [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md) [src/backend/tests/unit/components](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/tests/unit/components)
- Frontend testing: Jest (`npm test`) plus Playwright e2e under src/frontend/tests (a11y, core, extended, live, assets, fixtures), jest coverage and playwright-coverage merged via nyc and uploaded to Codecov; a11y-scan and a11y-unit-tests workflows exist. — [src/frontend/package.json](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/frontend/package.json) [src/frontend/tests](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/frontend/tests) [.github/workflows/ci.yml#L396-445](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.github/workflows/ci.yml#L396-L445)
- CI Python job matrixes Python 3.10 and 3.14, splits unit tests into groups via `make unit_tests args="--splits N --group G --reruns 5 --cov"`, and a separate job installs the bundles extra and runs only tests guarded by pytest.importorskip('lfx_bundles'). — [.github/workflows/python_test.yml#L59-114](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.github/workflows/python_test.yml#L59-L114) [.github/workflows/python_test.yml#L125-211](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.github/workflows/python_test.yml#L125-L211) [.github/workflows/ci.yml](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.github/workflows/ci.yml)
- Specialized CI: cross-platform-test, cross-bundle-test (bundle dependency range resolution), db-migration-validation, template-tests (runs test_starter_projects.py against all starter templates), docker_test/docker builds, CodeQL, smoke-tests, and stress-tests workflows. — [.github/workflows/ci.yml#L337-370](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.github/workflows/ci.yml#L337-L370) [.github/workflows/cross-bundle-test.yml](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.github/workflows/cross-bundle-test.yml) [.github/workflows/db-migration-validation.yml](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.github/workflows/db-migration-validation.yml)
- Integration tests are segregated under src/backend/tests/integration (coverage config ignores them: `--ignore=tests/integration`); there are also locust load tests (src/backend/tests/locust), a stress dir exempted from normal lint rules, and a `regressions/` folder of per-version YAML specs (1.9.x-1.12.x). — [pyproject.toml#L314-321](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L314-L321) [src/backend/tests/integration](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/tests/integration) [regressions/1.12.x.yaml](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/regressions/1.12.x.yaml) [pyproject.toml#L581-584](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L581-L584)
- Known test fragility is documented: DB tests 'may fail in batch but pass individually'; tests inside sub-packages need `uv sync --group dev --package <pkg>` first or dev deps like fakeredis are missing; tests set LANGFLOW_MODELS_DEV_REFRESH=false because the background fetch hits the network and trips pyleak. — [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md) [src/backend/base/langflow/main.py#L627-632](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L627-L632)

## Risk map

The dominant risk theme is executing caller-influenced code: custom components are arbitrary Python exec'd at build/validation time, stored flow JSON embeds component source, and multiple policy layers (custom_component_admin_only, tweak policy, owner-only tweaks, catalog/model-provider policy) exist to contain that. Auth surface risk is managed but default-lenient (AUTO_LOGIN, permissive CORS with warnings, SSRF protection off by default, short SECRET_KEY tolerated with legacy decryption). Supply-chain and infra footguns include remote bundle zips at startup, entry-point service replacement, per-worker in-memory job queues, and pickle in the cache service.
- Custom components execute arbitrary Python: lfx/custom/validate.py calls exec() on component code in several places (function extraction, class validation), explicitly noqa'd S102; code execution tools (python_repl) run user code gated by ensure_code_execution_enabled() + LANGFLOW_ALLOW_CUSTOM_COMPONENTS / LANGFLOW_BLOCK_CODE_INTERPRETER_COMPONENTS. — [src/lfx/src/lfx/custom/validate.py#L95-188](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/custom/validate.py#L95-L188) [src/lfx/src/lfx/components/tools/python_repl.py#L90-118](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/components/tools/python_repl.py#L90-L118) [src/lfx/src/lfx/utils/python_repl_security.py#L190-255](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/utils/python_repl_security.py#L190-L255)
- Stored flows carry component source: a regular user can persist component code via the flow-write API then execute it — mitigated by prepare_flow_build_for_user applying custom_component_admin_only policy to stored bytes on a detached copy before Graph.from_payload in both /run and /build paths. — [src/backend/base/langflow/api/v1/endpoints.py#L410-431](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L410-L431) [src/backend/base/langflow/api/v1/chat.py#L417-434](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/chat.py#L417-L434)
- An opt-in QEMU microVM sandbox backend (LANGFLOW_SANDBOX_BACKEND=exec-sandbox, extra `langflow-base[sandbox]`) exists for code-execution components; plugin backends are gated by LANGFLOW_SANDBOX_BACKEND_PLUGINS; shutdown_sandbox is called in lifespan cleanup so recycled workers don't leak VMs. — [src/lfx/src/lfx/utils/sandbox/exec_sandbox.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/utils/sandbox/exec_sandbox.py) [src/lfx/src/lfx/utils/sandbox/registry.py#L90-261](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/utils/sandbox/registry.py#L90-L261) [src/backend/base/langflow/main.py#L813-824](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L813-L824) [pyproject.toml#L202-208](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L202-L208)
- SSRF protection is OFF by default (LANGFLOW_SSRF_PROTECTION_ENABLED unset/false 'for backward compatibility'); when enabled it blocks private IP/localhost/metadata endpoints with an allowlist LANGFLOW_SSRF_ALLOWED_HOSTS — a meaningful default-off posture for a tool that fetches URLs. — [.env.example#L171-183](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.env.example#L171-L183)
- CORS defaults are permissive: wildcard origin + credentials historically enabled credentialed cross-site requests; code now force-disables credentials when '*' is present and warns that stricter defaults arrive in v2.0 — operators on current versions still get all-origins by default. — [src/backend/base/langflow/main.py#L167-189](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L167-L189) [src/backend/base/langflow/main.py#L879-906](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L879-L906)
- AUTO_LOGIN creates a superuser with a generated random password (legacy default password is ignored/rotated) guarded by a FileLock; teardown deletes the unused default superuser when AUTO_LOGIN is off — the warning text notes auto-login mode should not be exposed since access implies code execution. — [src/backend/base/langflow/services/utils.py#L141-263](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/utils.py#L141-L263) [src/backend/base/langflow/services/auth/utils.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/auth/utils.py) [src/lfx/src/lfx/utils/python_repl_security.py#L32](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/utils/python_repl_security.py#L32)
- SECRET_KEY handling: short secrets derive the Fernet key via SHA-256 for new encryption, but a MultiFernet retains a deterministic random.Random(seed)-derived legacy key for decryption — deployments with weak SECRET_KEYs keep weak key derivation, only warned about (MINIMUM_SECRET_KEY_LENGTH=32 warning). — [src/backend/base/langflow/services/auth/utils.py#L416-469](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/auth/utils.py#L416-L469) [src/lfx/src/lfx/services/settings/auth.py#L32-51](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/services/settings/auth.py#L32-L51)
- Remote bundle URLs (settings.bundle_urls) download zip archives (incl. GitHub repos) at startup and extract component files into temp dirs that are added to components_path — remote code is fetched and executed; errors are logged but never block startup. — [src/backend/base/langflow/initial_setup/setup.py#L1072-1146](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/initial_setup/setup.py#L1072-L1146) [src/backend/base/langflow/main.py#L159-164](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L159-L164)
- Entry-point plugin loading replaces service classes: any installed distribution can register `lfx.services` entry points; subclass validation exists only for AUTHORIZATION/CATALOG_POLICY/MODEL_PROVIDER_POLICY/POLICY_BUNDLE services, and lfx.toml config paths get override=True — a malicious/misconfigured package can swap less-guarded services. — [src/lfx/src/lfx/services/manager.py#L407-476](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/services/manager.py#L407-L476) [src/lfx/src/lfx/services/manager.py#L488-558](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/services/manager.py#L488-L558)
- Multi-worker state hazards are extensive: in-memory job queues break POLLING/STREAMING event delivery (~half of GET /build/<job_id>/events land on the wrong worker), MCP-over-SSE is broken, rate limits multiply per worker, orphan sweep is node-local — the guard refuses boot but the bypass env var exists. — [src/backend/base/langflow/__main__.py#L248-348](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L248-L348)
- Pickle is used intentionally in the cache service (ruff S301 waived for services/cache/*) — safe for local memory/SQLite but a deserialization risk if pointed at an untrusted/shared backend. — [pyproject.toml#L432-434](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L432-L434) [src/backend/base/langflow/services/cache/service.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/cache/service.py)
- worker.py is vestigial Celery code: test_celery/build_vertex tasks exist but process_graph_cached_task raises NotImplementedError('This task is not implemented yet') — dead execution path kept in the tree. — [src/backend/base/langflow/worker.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/worker.py)
- main.py is a 1277-line hotspot concentrating env-gated startup ordering; several comments document past races (UnboundLocalError on temp_dirs masking early failures, issue #13634; preload gating via is_step_complete to skip work in forked workers) — edit with care, ordering is load-bearing. (inferred) — [src/backend/base/langflow/main.py#L214-227](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L214-L227) [src/backend/base/langflow/main.py#L322-428](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L322-L428)
- MCP session manager spawns subprocesses for stdio servers; cleanup_mcp_sessions is deliberately first in the finally block so interrupted shutdowns still kill them; idle sessions are reaped by interval/timeout tunables clamped to prevent CPU spin. — [src/backend/base/langflow/main.py#L694-697](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L694-L697) [.env.example#L190-204](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/.env.example#L190-L204)

## Extension points

Langflow is built to be extended at five seams: (1) component/extension bundles via the `langflow.extensions` entry point + extension.json manifests + seed dirs + components_path; (2) service replacement via `lfx.services` entry points and lfx.toml/pyproject config (auth SSO, authorization/RBAC, catalog policy, model-provider policy, policy bundle); (3) HTTP route plugins via the `langflow.plugins` entry point with conflict-protected registration; (4) CLI plugins via register_cli_command_plugins; (5) enterprise hooks via the lifespan hook registry. Custom components subclass lfx Component and are discovered from directories.
- Route plugins: distributions registering a `langflow.plugins` entry point get a callable register(app) invoked with a _PluginAppWrapper that reserves every existing (path, method), refuses shadowing (RouteConflictError), and rolls back a half-registered plugin's routes on failure. — [src/backend/base/langflow/plugin_routes.py#L66-170](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/plugin_routes.py#L66-L170) [src/backend/base/langflow/plugin_routes.py#L173-234](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/plugin_routes.py#L173-L234) [src/backend/base/langflow/main.py#L1037-1038](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L1037-L1038)
- Service plugins: the `lfx.services` entry-point group registers service classes (override=False) and `lfx.toml`/`pyproject.toml [tool.lfx.services]` entries register with override=True; precedence is config > decorator > entry point, SETTINGS_SERVICE can never be overridden, and misconfigured MODEL_PROVIDER_POLICY/POLICY_BUNDLE services refuse to boot rather than fall back. — [src/lfx/src/lfx/services/manager.py#L366-405](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/services/manager.py#L366-L405) [src/lfx/src/lfx/services/manager.py#L477-558](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/services/manager.py#L477-L558)
- The OSS authorization layer is a designed plugin seam: LangflowAuthorizationService is a registered pass-through (every check allows) replaced by listing a real plugin class under `authorization_service` in lfx.toml — the same pattern documented for SSO via `auth_service`. — [src/backend/base/langflow/services/utils.py#L615-628](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/utils.py#L615-L628) [src/backend/base/langflow/services/authorization/service.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/authorization/service.py) [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md)
- Component/extension bundles: lfx-* packages ship an extension.json manifest inside the wheel and register a `langflow.extensions` entry point; discovery also scans LANGFLOW_SEED_DIR (default /opt/langflow/bundles) directories; inline bundles can come from components_path parents. — [src/bundles/openai/pyproject.toml#L36-50](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/bundles/openai/pyproject.toml#L36-L50) [src/lfx/src/lfx/extension/discovery.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/extension/discovery.py) [src/lfx/src/lfx/interface/components.py#L875-891](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/interface/components.py#L875-L891)
- Custom components: subclass lfx.custom.custom_component.component.Component (re-exported as langflow.custom.Component), declare display_name/inputs/outputs, drop the file under a components_path directory; LFX_DEV=1 / LFX_DEV=<modules> enables dynamic hot loading; directory_reader scans the paths. — [src/lfx/src/lfx/custom/custom_component/component.py#L165](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/custom/custom_component/component.py#L165) [src/lfx/src/lfx/custom/directory_reader/directory_reader.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/custom/directory_reader/directory_reader.py) [src/backend/base/langflow/custom/__init__.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/custom/__init__.py) [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md)
- Enterprise lifespan hooks: modules can append async callables to _enterprise_lifespan_hooks['startup'|'shutdown'] at app-construction time; startup hooks run after all services init, shutdown hooks run first in teardown; failures are logged and never block boot. — [src/backend/base/langflow/main.py#L81-99](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L81-L99) [src/backend/base/langflow/main.py#L657-703](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L657-L703)
- CLI plugins: lfx.cli.command_plugins.register_cli_command_plugins is invoked by the langflow Typer app so installed packages can add CLI subcommands; lfx's own commands are modular register(app) functions per group. — [src/lfx/src/lfx/cli/command_plugins.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/cli/command_plugins.py) [src/backend/base/langflow/__main__.py#L43](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L43) [src/lfx/src/lfx/__main__.py#L44-52](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/__main__.py#L44-L52)
- Deployment adapters/mappers: register_builtin_adapters + register_builtin_deployment_mappers import provider modules (e.g. watsonx_orchestrate) which register onto AdapterRegistry singletons — gated behind FEATURE_FLAGS.wxo_deployments. — [src/backend/base/langflow/services/utils.py#L650-683](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/utils.py#L650-L683) [src/backend/base/langflow/api/v1/mappers/deployments](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/mappers/deployments)
- Sandbox backend plugins: LANGFLOW_SANDBOX_BACKEND_PLUGINS whitelists which entry-point plugins may load an executor backend for code-execution components; the default backend is 'none'. — [src/lfx/src/lfx/utils/sandbox/registry.py#L192-325](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/utils/sandbox/registry.py#L192-L325)
- Frontend white-label seams: CustomRoutesStore/CustomAuthRoutesStore/CustomRoutesStorePages in routes.tsx let deployments override routes/pages, and icons register via lazyIconImports; the frontend only talks to the backend over HTTP/WS. — [src/frontend/src/routes.tsx#L21-51](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/frontend/src/routes.tsx#L21-L51) [docs/agents/ARCHITECTURE.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/docs/agents/ARCHITECTURE.md)

## Contributor handoff

Onboarding essentials: this is a uv workspace — always `uv run` Python commands, sync sub-package dev groups before testing inside them, run `make format_backend` before committing (ruff select=ALL, line-length 120, big per-file-ignore table), and respect the one-way dependency direction (lfx never imports langflow.*). Component class names are stable identifiers — never rename. Flow JSON shape is a contract. DB model changes require alembic revisions. The service layer is registry-driven: add services via factories + ServiceType, not globals. Highest-risk edit zones: main.py lifespan ordering, endpoints.py/build.py/chat.py auth+policy ordering, and anything that executes stored component code.
- Read first: AGENTS.md (commands + component rules), docs/agents/ARCHITECTURE.md (dependency rules + 'where does code go' decision tree), src/backend/base/langflow/main.py (app wiring + lifespan), services/deps.py + services/utils.py (service registry + init order), api/router.py (route map), api/v1/endpoints.py (run path), lfx/services/manager.py (plugin discovery). — [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md) [docs/agents/ARCHITECTURE.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/docs/agents/ARCHITECTURE.md) [src/backend/base/langflow/services/deps.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/deps.py) [src/backend/base/langflow/api/router.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/router.py)
- Commands: `make init` (uv sync --frozen --extra postgresql + npm install + pre-commit), `make backend`/`make frontend` for dev servers, `LFX_DEV=1 make backend` for dynamic component loading, `make unit_tests` / `uv run pytest path::test`, `make lint` (mypy), `uv run git commit` (pre-commit needs uv's env). — [Makefile](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/Makefile) [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md)
- Sub-package test trap: `uv sync` only resolves the top-level workspace; tests inside langflow-base or lfx need `uv sync --group dev --package langflow-base` (etc.) first or dev-only deps like fakeredis are missing and tests fail oddly. — [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md) [pyproject.toml#L88](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L88)
- Never rename a Component class — the class name is the persisted identifier matching components in saved flows and flagging UI updates; renaming breaks existing flows. New components go in src/bundles/<provider>/ (with extension.json) or lfx/components, inheriting lfx Component. — [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md) [docs/agents/ARCHITECTURE.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/docs/agents/ARCHITECTURE.md) [src/lfx/src/lfx/custom/custom_component/component.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/lfx/src/lfx/custom/custom_component/component.py)
- Dependency direction is enforced by convention: lfx MUST NOT import langflow.* (langflow-base installs the `langflow` package); langflow-base must not import vendor component modules; shared primitives go in lfx/base, never langflow/base; lfx-* bundles must not import application services. — [docs/agents/ARCHITECTURE.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/docs/agents/ARCHITECTURE.md)
- DB changes: models live in services/database/models/*; every change needs `make alembic-revision` + `make alembic-upgrade`; alembic/versions is excluded from ruff; note async-session traps — cascade_delete_flow lists updatable columns explicitly because getattr on unloaded relationships raises MissingGreenlet. — [src/backend/base/langflow/api/utils/flow_utils.py#L1149-1174](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/utils/flow_utils.py#L1149-L1174) [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md) [pyproject.toml#L419](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L419)
- Async discipline: blockbuster flags blocking calls in tests; use session_scope() (get_session raises NotImplementedError); DB tests can fail in batch but pass individually; set LANGFLOW_MODELS_DEV_REFRESH=false to keep the network-touching refresh task out of tests. — [src/backend/base/langflow/services/deps.py#L158-181](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/services/deps.py#L158-L181) [src/backend/base/langflow/main.py#L627-632](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py#L627-L632) [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md)
- Security invariants to preserve when editing run paths: owner-only tweaks (_enforce_owner_only_tweaks), deny->404 UUID-privacy reframes (deny_to_404_unless_readable), public-flow file namespace regex, session namespacing, and prepare_flow_build_for_user before any stored graph executes — these encode prior CVEs. — [src/backend/base/langflow/api/v1/endpoints.py#L136-146](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L136-L146) [src/backend/base/langflow/api/v1/chat.py#L365-406](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/chat.py#L365-L406) [src/backend/base/langflow/api/utils/flow_utils.py#L144-218](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/utils/flow_utils.py#L144-L218)
- Lint conventions: ruff select=ALL at line-length 120 with google docstrings; intentional violations are codified per-file (exec in lfx/custom/validate.py, pickle in services/cache, SLF001 for MCP/third-party internals) — match the pattern or add a justified per-file-ignore; frontend uses biome + tsc --noEmit. — [pyproject.toml#L347-584](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/pyproject.toml#L347-L584) [src/frontend/package.json](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/frontend/package.json)
- Version bumps: `make patch v=X.Y.Z` updates pyproject.toml, src/backend/base/pyproject.toml, src/frontend/package.json together; bundle lfx pins are re-synced by scripts/ci/sync_bundle_lfx_pin.py — don't hand-edit versions in only one manifest. — [AGENTS.md](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/AGENTS.md) [src/bundles/openai/pyproject.toml#L17-22](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/bundles/openai/pyproject.toml#L17-L22)
- Hotspot map: main.py (1277 lines) encodes fragile startup ordering documented by inline issue references; __main__.py's ensure_multi_worker_safe guards a real race; endpoints.py's auth/widening wrappers exist because raw Depends helpers once bypassed user scoping — preserve the wrapper pattern. (inferred) — [src/backend/base/langflow/main.py](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/main.py) [src/backend/base/langflow/__main__.py#L291-348](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/__main__.py#L291-L348) [src/backend/base/langflow/api/v1/endpoints.py#L807-858](https://github.com/langflow-ai/langflow/blob/5621dcfd84e11108e4cc1ecb0c51f41053c4211c/src/backend/base/langflow/api/v1/endpoints.py#L807-L858)

Source repository: https://github.com/langflow-ai/langflow
Full evidence corpus: https://github.com/Codevetter/codevetter/tree/main/benchmarks/repo-unpacks/langflow.json

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)