feat: add flow version control

[jordanrfrazier]

Adds version control for individual Flows.

Summary by CodeRabbit

Release Notes

• New Features

  • Added flow versioning system: create snapshots of flows, view version history, and restore previous versions.
  • Added version preview overlay to inspect historical flow states without modifying the current draft.
  • Added history export and import support for flows, including optional data stripping for sensitive information.
  • Added configurable limits for history entries and snapshot data size.

• Bug Fixes

  • Fixed potential null reference errors when processing flow node structures.

• Tests

  • Added comprehensive test coverage for version history operations, including create, restore, delete, and export functionality.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2e497fb7-b3b5-45b8-aa5e-95f905e25d5a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

This PR adds a complete flow version history feature. It introduces a new flow_history database table with CRUD operations, RESTful API endpoints for creating snapshots, listing versions, restoring historical versions, and deleting entries. The frontend provides a sidebar panel for version management, a read-only preview overlay, and import/export integration. Configuration settings control per-flow entry limits and data size constraints.

Changes

Cohort / File(s)	Summary
Database Migration & Core Models alembic/versions/7d327cfafab6_add_flow_history_table.py, services/database/models/flow_history/model.py, services/database/models/flow_history/exceptions.py	New Alembic migration creates flow_history table with versioning constraints. SQLModel defines FlowHistory with related read/create schemas. Exception hierarchy (FlowHistoryError, NotFoundError, DataTooLargeError, etc.) for domain-specific error handling.
Database CRUD & Utilities services/database/models/flow_history/crud.py, services/database/models/flow_history/__init__.py, services/database/models/__init__.py, api/utils/core.py	CRUD layer with versioning logic (retries on conflicts), concurrency-safe pruning, and async retrieval helpers. cascade_delete_flow now explicitly deletes FlowHistory records. Core utilities export DbSessionReadOnly. Package exports centralize public API surface.
Backend API Router & Endpoints api/router.py, api/v1/__init__.py, api/v1/flow_history.py	Flow history router integrated into v1 API. New endpoints: list history (GET /flows/{flow_id}/history), create snapshot (POST /), get entry (GET /{history_id}), activate version (POST /{history_id}/activate), delete entry (DELETE /{history_id}), export with history (GET /export). Includes error translation, data stripping, and savepoint-based atomicity.
Flow Import/Export Integration api/v1/flows.py	Enhanced upload_file and download_multiple_file to optionally import/export flow history. Preserves history data during upload; fetches and embeds history in exports (GET and POST paths). Validates, serializes, and handles failures gracefully with summary logging.
Frontend Query Hooks src/frontend/src/controllers/API/queries/flow-history/*	Four React Query hooks: useGetFlowHistory (list), useGetFlowHistoryEntry (single fetch), usePostCreateSnapshot (mutation), useDeleteHistoryEntry (mutation with refetch). Central aggregator index for clean imports.
Frontend State & Types src/frontend/src/stores/historyPreviewStore.ts, src/frontend/src/types/flow/history.ts	Zustand store manages preview nodes/edges/label with key-based remounting. TypeScript types define FlowHistoryEntry, FlowHistoryEntryWithData, FlowHistoryCreate, and list response shape.
Frontend UI Components src/frontend/src/pages/FlowPage/components/flowSidebarComponent/components/FlowHistorySidebarContent.tsx, src/frontend/src/pages/FlowPage/components/PageComponent/index.tsx, src/frontend/src/pages/FlowPage/components/flowSidebarComponent/index.tsx, src/frontend/src/pages/FlowPage/consts.ts, src/frontend/src/pages/FlowPage/index.tsx	FlowHistorySidebarContent renders version list, "Current Draft", create/restore/export/delete actions with portaled modals. PageComponent adds read-only preview overlay with ReactFlowProvider and error boundary. New useApplyFlowToCanvas hook coordinates flow loading, processing, and input refresh. Sidebar integration conditionally renders history panel. Central consts export node/edge types.
Frontend Additional UI src/frontend/src/components/ui/dropdown-menu.tsx, src/frontend/src/components/ui/sidebar.tsx, src/frontend/src/modals/exportModal/index.tsx	DropdownMenuContent accepts optional container prop for portal targeting. SidebarSection adds "history" literal with non-persistent flag. Export modal adds include_history checkbox and calls history export endpoint on fetch.
Configuration & Logging src/lfx/src/lfx/services/settings/base.py, src/lfx/src/lfx/base/models/unified_models.py	Settings adds max_flow_history_entries_per_flow (50) and max_flow_history_data_size_bytes (10 MB). Enhanced logging in _get_default_model with var_name and user_id context.
Backend Tests src/backend/tests/unit/api/test_api_utils.py, src/backend/tests/unit/api/v1/test_flow_history.py	Extended test_api_utils with sparse node structure validation. Comprehensive 1321-line test suite covering snapshot creation, versioning, listing, retrieval, activation (with auto-save), deletion, cascade behavior, history pruning, import/export round-trips, API key redaction, large payloads, and edge cases.
Frontend Tests src/frontend/src/pages/FlowPage/components/flowSidebarComponent/components/__tests__/FlowHistorySidebarContent-export.spec.tsx, src/frontend/src/pages/FlowPage/components/flowSidebarComponent/components/__tests__/FlowHistorySidebarContent-store.spec.tsx, src/frontend/src/pages/FlowPage/components/flowSidebarComponent/components/__tests__/sidebarSegmentedNav.test.tsx	Component export behavior test, store synchronization test, and nav item count assertion. Mocked API, stores, and utilities to validate end-to-end version export, store restoration, and UI state transitions.
Utility Updates api/utils/__init__.py	Re-export DbSessionReadOnly for explicit module API clarity.

Sequence Diagram

sequenceDiagram
    actor User
    participant Client as Frontend Client
    participant API as Flow History API
    participant Service as History Service
    participant DB as Database

    User->>Client: Click version to activate
    Client->>API: POST /flows/{flow_id}/history/{history_id}/activate
    API->>Service: get_flow_history_entry_or_raise (validate ownership)
    Service->>DB: Query FlowHistory by ID
    DB-->>Service: FlowHistory record
    API->>Service: Optionally auto-save current draft
    Service->>Service: create_flow_history_entry (current state)
    Service->>DB: Insert new FlowHistory (snapshot)
    DB-->>Service: Version created
    API->>DB: Begin savepoint transaction
    Service->>DB: Update Flow.data with historical version data
    DB-->>Service: Confirmation
    API->>DB: Commit savepoint
    API-->>Client: Updated Flow with restored data
    Client->>Client: applyFlowToCanvas (refresh canvas & inputs)
    Client-->>User: Preview overlay synced to activated version

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~70 minutes

🚥 Pre-merge checks | ✅ 3 | ❌ 4

❌ Failed checks (1 error, 3 warnings)

Check name	Status	Explanation	Resolution
Test Coverage For New Implementations	❌ Error	PR lacks dedicated unit tests for critical backend CRUD and frontend custom hooks layers, relying only on integration tests.	Create unit test files for CRUD functions, custom hooks, and stores following project conventions to enable faster layer-specific feedback.
Docstring Coverage	⚠️ Warning	Docstring coverage is 54.37% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Test File Naming And Structure	⚠️ Warning	Frontend test files lack required documentation comments explaining test purpose, scenarios, and expected outcomes per test case.	Add purpose/scenario/expected-outcome comments to each test case in FlowHistorySidebarContent-export.spec.tsx and FlowHistorySidebarContent-store.spec.tsx to document test intent.
Excessive Mock Usage Warning	⚠️ Warning	Frontend tests use excessive mocking (15 mocks for 3-9 tests) that obscures actual component behavior, while backend tests properly use real integration testing with minimal mocking.	Refactor frontend tests to selectively mock only API boundaries, use real Zustand stores, remove UI component mocks, and add integration tests to validate actual component behavior.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Test Quality And Coverage	✅ Passed	Pull request includes comprehensive test coverage for flow history functionality with 1321 lines of backend tests and 709 lines of frontend tests covering create, snapshot, history, activate, delete, export, import, and edge cases.
Title check	✅ Passed	The pull request title 'feat: add flow version control' accurately summarizes the main change—introducing comprehensive flow history/versioning functionality with database migration, API endpoints, CRUD operations, and frontend UI components.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch workflow-history

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

✅ Migration Validation Passed

All migrations follow the Expand-Contract pattern correctly.

[github-actions]

Frontend Unit Test Coverage Report

Coverage Summary

Lines	Statements	Branches	Functions
	23.24% (8225/35389)	16% (4449/27792)	15.92% (1185/7441)

Unit Test Results

Tests	Skipped	Failures	Errors	Time
2631	0 💤	0 ❌	0 🔥	46.086s ⏱️

[codecov]

Codecov Report

❌ Patch coverage is 45.45455% with 414 lines in your changes missing coverage. Please review.
✅ Project coverage is 37.46%. Comparing base (06f861d) to head (ffc2754).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/backend/base/langflow/api/v1/flow_version.py	46.01%	61 Missing ⚠️
...nts/FlowVersionSidebar/use-flow-version-sidebar.ts	72.25%	21 Missing and 22 partials ⚠️
...flow/services/database/models/flow_version/crud.py	39.68%	38 Missing ⚠️
...ts/PageComponent/components/SaveSnapshotButton.tsx	0.00%	32 Missing ⚠️
.../pages/FlowPage/components/PageComponent/index.tsx	0.00%	28 Missing ⚠️
.../PageComponent/components/RestoreVersionButton.tsx	0.00%	26 Missing ⚠️
...ontend/src/hooks/flows/use-apply-flow-to-canvas.ts	0.00%	22 Missing ⚠️
...FlowPage/components/flowSidebarComponent/index.tsx	0.00%	22 Missing ⚠️
...mponents/PageComponent/components/CanvasBanner.tsx	0.00%	20 Missing ⚠️
...PageComponent/components/VersionPreviewOverlay.tsx	0.00%	17 Missing ⚠️
... and 18 more

❌ Your project status has failed because the head coverage (42.37%) is below the target coverage (60.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #11859      +/-   ##
==========================================
+ Coverage   37.35%   37.46%   +0.10%     
==========================================
  Files        1592     1616      +24     
  Lines       78304    79014     +710     
  Branches    11826    11936     +110     
==========================================
+ Hits        29247    29599     +352     
- Misses      47435    47761     +326     
- Partials     1622     1654      +32     

Flag	Coverage Δ
backend	57.39% <57.87%> (+0.03%)	⬆️
frontend	20.82% <39.73%> (+0.32%)	⬆️
lfx	42.37% <66.66%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/backend/base/langflow/api/router.py	100.00% <100.00%> (ø)
src/backend/base/langflow/api/utils/core.py	64.04% <100.00%> (+1.38%)	⬆️
src/backend/base/langflow/api/v1/flows.py	52.61% <ø> (ø)
...ervices/database/models/flow_version/exceptions.py	100.00% <100.00%> (ø)
...low/services/database/models/flow_version/model.py	100.00% <100.00%> (ø)
src/frontend/src/components/ui/sidebar.tsx	51.63% <ø> (ø)
...mponent/components/FlowVersionSidebar/constants.ts	100.00% <100.00%> (ø)
...Component/components/FlowVersionSidebarContent.tsx	100.00% <100.00%> (ø)
...idebarComponent/components/sidebarSegmentedNav.tsx	98.03% <ø> (ø)
src/lfx/src/lfx/services/settings/base.py	73.70% <100.00%> (+0.11%)	⬆️
... and 28 more

... and 7 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.