The three data stores and their roles:

• Yjs data: Yjs is the single source of truth in terms of canvas operations. It is in store.ydoc.nodesMap. This data is shared by all peers. The canvas is rendered from this data.
• DB data: On canvas loading, if Yjs data is empty or inconsistent with the database, overwrite Yjs data with database data. That is, the database is the single source of truth in terms of eventual consistency.
• Zustand store: The local Zustand store is used to store graph structure and metadata, as well as handle DB writes.

The files: the main logic is implemented in three files:

• lib/nodes.tsx: this implements Yjs observer
• components/Canvas.tsx: implements the Canvas React component.
• lib/store/canvasSlices.tsx: actually implements all the operations (updateView, copy/paste/cut logic)

How the canvas nodes are rendered?

The ReactFlow canvas data is stored in store.nodes, and passed to <ReactFlow nodes={store.nodes}/>. Updating this state will trigger a canvas re-rendering. Only one action is allowed to actually update the nodes, the updateView function. Other actions are supposed to call it whenever a re-rendering is desired.

The updateView action computes the new nodes from the following data sources:

• All nodes in Yjs nodesMap.
• The pasting/cutting node. Note: these temporary nodes are maintained outside nodesMap because they are local to the local user.

Additional logic is implemented in updateView to modify the nodes, e.g.,

• add background color according to scope level;
• set the className for cutting nodes and active scope.

Handling the changes made by remote peers

All changes made by remote peers are observed with useYjsObserver(). These observed changes (add,remove,update) will

1. Write to the local Zustand store without DB sync.
2. trigger updateView action to update the canvas.

Handling the changes made by the local user

Overall, the local user's changes will

1. write to nodesMap to sync with remote peer
2. write to zustand store, sync with DB (using the dirty=true flag), then call updateView to update canvas.

The specific logic for each Canvas operation:

• Add node:
  1. Update nodesMap to sync with the remote peer.
  2. Do local updates (zustand store, db, updateView)
• Move a node: onNodesChange will observe the change. It calls applyChange to compute new nodes, and do:
  1. Set nodesMap to sync with the remote peer
  2. Do local updates (zustand store, db, updateView)
  3. Check if this is moved into scope. (handled by <ReactFlow onNodeDragStop={...}>)
• Select nodes: onNodesChange observe the selection event, and record and update the local canvas.
• Remove node:
  1. nodesMap.delete to sync with peer
  2. Do local updates (zustand store, db, updateView)
• Paste
  • Begin (triggered by ctrl-v)
    • Create and set store.pastingNode. Set store.isPasting flag.
  • onMove: The "move" event listener will set store.pastingNode's position and update the view so that the pod will follow the cursor.
  • End:
    1. Update nodesMap to sync with the remote peer
    2. Do local updates (zustand store, db, updateView)
    3. Check if dropped into a scope. If so, call store.moveIntoScope action to update parentNode and recompute all scopes' levels.
  • Cancel: clear the pastingNode and isPasting
• Cut (triggered by clicking the cut button): similar to pasting.