Real-time Collaboration

FlowCollaborationEngine is based on WebSocket and lightweight CRDT (LWW Register / G-Counter) to achieve multi-user real-time editing of Flow, supporting cursor synchronization, selection synchronization, and conflict resolution. The collaboration engine provides connect, disconnect, and event listeners, which can be directly interfaced with existing WebSocket services.

Collaboration Architecture

• CRDT State: Locally maintains Maps of nodes, edges, and viewport, processing concurrent updates combined with the LWW register.
• WebSocket Messages: join/leave/operation/sync/cursor/selection six message types, used for room management, state synchronization, and instant interaction.
• Event Callbacks: Supports sync, operation, cursor_update, user_joined, user_left events, making it easy for UI response.
• Reconnection Mechanism: Automatic exponential backoff reconnection, up to 5 attempts.

Core API

API	Description
connect(options)	Connect to a collaboration room (serverUrl, roomId, userId, userName, initialNodes/Edges)
disconnect()	Disconnect and clean up heartbeats
addNode(node) / updateNode(nodeId, updates) / deleteNode(nodeId)	Local operations are automatically broadcasted
addEdge(edge) / updateEdge(edgeId, updates) / deleteEdge(edgeId)	Edge operations synchronization
updateViewport(viewport) / updateCursor(x, y) / updateSelection(nodeIds)	Viewport and interaction synchronization
getState() / getCursors() / getConnectionState()	Query current state
on(event, callback) / off(event, callback)	Event subscription

Example

The example below demonstrates how to initialize the collaboration engine, connect to a room, listen for events, and display user cursors and status in the UI.

Start

Collaborative Edit

End

Status: disconnected

Real-time Collaboration Example

Best Practices

1. Integrate with Business WebSocket Service: Replace the serverUrl in connect with your collaboration backend address; the backend only needs to forward messages.
2. Local First: All local operations take effect immediately, while network synchronization is completed asynchronously via operation messages. The LWW mechanism ensures eventual consistency.
3. Handle Conflicts: Monitor remote updates via on('operation'), enabling conflict UI prompts or rollbacks for specific nodes/edges.
4. Optimize Cursor & Selection: Use unreliable transmission for updateCursor and updateSelection to avoid frequent network jitter from impacting the user experience.