Feat: Add flow versioning system with master-version pattern

[AhmedRaafat14]

Summary

Implements a comprehensive versioning system for ChatFlows and AgentFlows, allowing users to create, manage, and switch between multiple versions of their flows.

Problem

Currently, I face some problems when I need to update an existing flow without losing my existing one, I faced these problems:

• Manually duplicate the entire flow
• Make changes to the duplicated copy
• Manage multiple separate flows that are conceptually versions of the same flow
• With every new flow, users have to update the client by calling the predications endpoint with the new flow ID.

This leads to cluttered flow lists, no clear version history, difficulty rolling back, and risk of deploying the wrong version.

Solution

Implements a Master-Version Pattern that:

• Maintains a stable master flow ID that never changes
• Stores each version as a separate record linked to the master
• Allows users to view, create, and manage versions through the UI
• Supports draft/publish workflow for safe iterative development

I have implemented these changes in my self-hosted version of Flowise and have been using it for some time now, so it would be useful to share with the community and give back.

Key Features

• Version History Modal: View all versions with metadata (timestamp, creator, description)
• Active Version Management: Designate which version is used by APIs/predictions
• Version Indicator: Shows current version status in canvas header
• Create From Any Version: Fork new versions from any existing version
• Backward Compatible: Existing flows auto-migrate to v1, all existing API endpoints continue to work
• Query Specific Version: Allow to call API like this api/v1/prediction/{ID}/versions/{VERSION_NUMBER}, this allows you to test a specific version before publishing it.

Database Changes

New Tables

• chat_flow_master - Stores high-level flow metadata with stable ID
• chat_flow_version - Stores individual versions with complete configuration

Migrations

• Schema migrations for all 4 supported databases (PostgreSQL, MySQL, MariaDB, SQLite)
• Data migrations to convert existing chat_flow records to a versioned structure
• Existing flows become version 1 with isActive = true.

API Endpoints

Method	Endpoint	Description
GET	/api/v1/chatflows/:id/versions	List all versions
GET	/api/v1/chatflows/:id/versions/:version	Get specific version
POST	/api/v1/chatflows/:id/versions	Create new version
PUT	/api/v1/chatflows/:id/versions/:version	Update version
PUT	/api/v1/chatflows/:id/active-version	Set active version
DELETE	/api/v1/chatflows/:id/versions/:version	Delete version

Files Changed

Backend (New)

• packages/server/src/database/entities/ChatFlowMaster.ts
• packages/server/src/database/entities/ChatFlowVersion.ts
• packages/server/src/services/chatflow-versions/index.ts
• packages/server/src/controllers/chatflow-versions/index.ts
• packages/server/src/routes/chatflow-versions/index.ts
• Database migrations for PostgreSQL, MySQL, MariaDB, SQLite

Frontend (New)

• packages/ui/src/ui-component/dialog/VersionHistoryDialog.jsx.

Modified

• packages/server/src/Interface.ts - Added interfaces
• packages/server/src/routes/index.ts - Registered routes
• packages/ui/src/api/chatflows.js - Added API methods
• packages/ui/src/views/canvas/index.jsx - Version state & handlers
• packages/ui/src/views/canvas/CanvasHeader.jsx - Version UI components
• packages/ui/src/views/agentflowsv2/Canvas.jsx - AgentFlow version support

Test Plan

• Create new flow → v1 is created automatically
• Publish new version → new version created and set as active
• View version history → all versions displayed with metadata
• Load specific version → canvas updates with that version's data
• Set active version → API uses correct version for predictions
• Delete non-active version → deletion succeeds
• Try delete active version → error message shown
• Try delete last version → error message shown
• Create version from older version → new version created with source tracking
• Existing flows after migration → work as v1 with no breaking changes

Breaking Changes

None - fully backward compatible. All existing API endpoints and flows continue to work without modification.

Recording

Flow_Versioning.1.mp4

[gemini-code-assist]

Summary of Changes

Hello @AhmedRaafat14, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the platform's capabilities by introducing a comprehensive versioning system for ChatFlows and AgentFlows. It addresses the challenges of managing flow updates by providing a structured approach to track changes, maintain drafts, and designate active versions. This feature streamlines the development lifecycle of conversational AI flows, making it easier for users to iterate, test, and deploy changes safely and efficiently.

Highlights

• Comprehensive Versioning System: Introduces a robust versioning system for both ChatFlows and AgentFlows, allowing users to create, manage, and switch between multiple iterations of their flows without manual duplication.
• Master-Version Pattern: Implements a 'Master-Version Pattern' where a stable master flow ID persists, and individual versions are stored as separate records linked to this master, ensuring clear version history and management.
• New Database Schema and Migrations: Adds two new database tables, chat_flow_master and chat_flow_version, along with schema and data migrations for PostgreSQL, MySQL, MariaDB, and SQLite to support the new versioning structure. Existing flows are automatically migrated to version 1.
• New API Endpoints: Exposes a suite of new API endpoints for managing versions, including operations to list all versions, retrieve a specific version, create new versions, update existing versions, set an active version, and delete versions.
• Enhanced UI for Version Management: Integrates new UI components, such as a 'Version History Modal' to view versions with metadata, an active version indicator in the canvas header, and functionalities to create new versions from existing ones, and publish changes.
• Backward Compatibility: Ensures full backward compatibility, meaning existing API endpoints and flows will continue to function without any breaking changes, with current flows automatically becoming version 1.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive versioning system for chatflows, a significant and valuable feature. The implementation includes new backend tables, services, and endpoints, along with corresponding frontend components for version management. The database migrations are well-crafted for all supported databases.

My review has identified a few areas for improvement to enhance the robustness and correctness of this new feature. I've pointed out a potential race condition in the version creation logic, a critical bug in the canvas component that could lead to loading stale data, and some minor code style issues. Addressing these points will help ensure the versioning system is reliable and maintainable.

[AhmedRaafat14]

/gemini review

[gemini-code-assist]

Code Review

This is a comprehensive and well-executed pull request that introduces a much-needed versioning system for chatflows. The implementation of the Master-Version pattern is thorough, covering database migrations, new API endpoints, and frontend UI changes. The backward compatibility is a huge plus. My feedback focuses on improving maintainability by reducing code duplication in the backend services and controllers, and enhancing code readability in the frontend components. All original comments were kept as they did not contradict the provided rule regarding generic images for error pages.

[AhmedRaafat14]

/gemini review

[gemini-code-assist]

Code Review

This is a significant and well-executed feature that introduces a comprehensive versioning system for flows. The implementation is thorough, covering database migrations for all supported systems, new backend services and endpoints, and a well-integrated UI for version management. The master-version pattern is a solid approach, and the backward compatibility for existing flows is a huge plus. My review focuses on a few opportunities to improve maintainability by reducing code duplication and improving type safety, which are common in a feature of this scale.

[AhmedRaafat14]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive versioning system for ChatFlows and AgentFlows, which is a significant and well-executed feature. The changes are extensive, touching the backend, frontend, and database, including migrations for all supported database systems. The implementation of the master-version pattern is solid, with good use of database transactions to ensure data integrity. The frontend changes provide a clear and intuitive user experience for managing versions. Overall, this is an excellent contribution that greatly enhances the platform's capabilities. I've pointed out a potential unintentional feature removal and a couple of minor code quality improvements.

I am having trouble creating individual review comments. Click here to see my feedback.

packages/server/src/services/export-import/index.ts (804-960)

The function exportChatflowMessages and its helpers have been removed in this pull request. This appears to be a feature removal that is not mentioned in the PR description. If this is unintentional, it should be restored. If it's an intentional change, it would be good to document it as a breaking change.

packages/server/src/services/export-import/index.ts (639)

The queryRunner variable is not typed. For better type safety and code clarity, it should be explicitly typed as QueryRunner.

    let queryRunner: QueryRunner

packages/ui/src/views/canvas/CanvasHeader.jsx (254-257)

This function _onSaveChatflowClick seems to be unused after refactoring the save button logic. It can be removed to improve code clarity.

[HenryHengZJ]

thank you so much @AhmedRaafat14 for the PR! we were also having similar work under development, although there is some difference. Main thing being we also wanted to change how API access should be together with publishing and versioning:

• Everry new flow will now opened as draft, and all existing flows by default will be published to avoid disruption.
• Users can save the draft, but will not create a new version
• Once user is happy with the flow, it can be published. This will then create a new version
• Users can then do the same as what you did on this PR, going back and forth between different version, and make a new draft from a specific version
• Only published flows can be called by Prediction API with an API key or a valid session token