# Contributor handoff — langflow-ai/langflow

> Canonical page: https://codevetter.com/unpack/langflow/agent-handoff

# Contributor handoff — langflow-ai/langflow

Scanned commit 5621dcfd84e11108e4cc1ecb0c51f41053c4211c (2026-09-15). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

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)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

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