Principle:FlowiseAI Flowise Chatflow Persistence

Attribute	Value
Source Repository	FlowiseAI/Flowise
Domain	Chatflow_Creation
Workflow	Chatflow_Creation
Last Updated	2026-02-12

Overview

Technique for serializing and persisting a visual flow graph to server-side storage with create/update semantics. After users build a flow on the canvas, the entire graph state (nodes, edges, viewport) must be serialized and saved to the server. Uses create-or-update semantics: new flows call create, existing flows call update.

Motivation

A visual flow editor is only useful if the work can be saved and restored. Without persistence:

• Users would lose their entire flow configuration when leaving the page or refreshing the browser.
• Flows could not be deployed, shared, or versioned.
• The chatflow execution engine would have no graph to process when receiving prediction requests.

Persistence bridges the gap between the in-memory ReactFlow graph state and durable server-side storage, enabling the full lifecycle of chatflow creation, testing, deployment, and iteration.

Description

The Chatflow Persistence principle follows the standard CRUD create/update pattern with client-side graph serialization. The entire flow graph is serialized to JSON and sent to the server as a single atomic payload.

Serialization

The ReactFlow library provides a toObject() method on the flow instance that captures the complete graph state:

const rfInstanceObject = reactFlowInstance.toObject()
// Returns:
// {
//   nodes: [...],     // Array of node objects with positions, data, dimensions
//   edges: [...],     // Array of edge objects with source/target handles
//   viewport: {       // Current pan/zoom state
//     x: number,
//     y: number,
//     zoom: number
//   }
// }

Before serialization, credential IDs are extracted from node inputs and moved to a top-level credential field on the node data, and the selected flag is reset to false on all nodes.

Create vs. Update

The save operation uses create-or-update semantics:

1. New chatflow (no ID) -- If the chatflow has no server-assigned ID, the system calls the create endpoint with the flow name, serialized flow data, deployment status, and type.
2. Existing chatflow (has ID) -- If the chatflow already has a server-assigned ID, the system first checks whether the chatflow has been modified by another user since it was loaded (optimistic concurrency check). If confirmed, it calls the update endpoint with the chatflow ID and the updated fields.

Concurrency Check

Before updating an existing chatflow, the system queries the server to determine if the chatflow has been modified since the current user loaded it. If the server reports changes, the user is prompted to confirm overwriting. This prevents accidental data loss in multi-user scenarios.

Save Flow

The complete save sequence:

1. User clicks Save in the CanvasHeader component.
2. handleSaveFlow(chatflowName) is called.
3. Node data is preprocessed (credential extraction, selection reset).
4. reactFlowInstance.toObject() serializes the graph.
5. The serialized JSON is sent to the server via create or update API.
6. On success, the dirty flag is cleared and the user receives a success notification.

Theoretical Basis

This principle is grounded in standard CRUD create/update persistence with client-side serialization:

• Atomic save -- The entire graph is serialized and sent as a single payload, ensuring consistency. There are no partial saves of individual nodes or edges.
• Optimistic concurrency control -- Before updating, the system checks if the resource has been modified by another user. This follows the "check-then-act" pattern common in collaborative editing systems.
• Separation of graph state and persistence format -- The in-memory ReactFlow graph state (with live React components, event handlers, and rendering metadata) is converted to a pure data representation for storage. This separation allows the graph to be restored from the serialized form without coupling storage to the rendering library.
• Create-or-update semantics -- The save operation transparently handles both new and existing flows, abstracting the distinction from the user.

Usage

Use this principle when implementing save functionality for a visual flow editor that needs server-side persistence. It applies to:

• Saving new chatflow configurations to the server for the first time.
• Updating existing chatflow configurations with modified graph state.
• Implementing optimistic concurrency control for multi-user editing scenarios.
• Serializing ReactFlow graph state into a portable JSON format.

Related Pages

• Implementation:FlowiseAI_Flowise_CreateNewChatflow