Skip to main content

Single Interactions

This document details individual canvas interactions and their effects on the mutation tracking system.

Node Operations​

Node Creation​

Node creation always originates from the canvas's flow palette. Users can:

  • Click a "Create [Node Type]" button - Creates a fresh node with default data
  • Select an existing node to add - Uses Copy-On-Use pattern, duplicating entity data

Mutation Impact:

  • Creates a CREATE command for the new entity
  • If edges are auto-created, additional implied mutations are captured
  • Node receives a temporary ID until saved

Node Selection​

Selected nodes are highlighted with a visual border and can be moved, updated, or deleted.

  • User clicks a node to select it
  • User Shift+clicks to multi-select
  • Selection state is UI-only (no mutation)
note

Selection is a canvas state, not a tracked interaction. No commands are created for selection changes.

Node Movement​

Node movement is triggered when a user drags a selected node to a new position.

Key Behavior:

  • Position changes affect canvas_data only
  • No mutation command is created
  • Entity data remains unchanged
// Position stored in canvas_data, not entity
{
  canvas_data: {
    nodes: [{ id: 'node-1', position: { x: 100, y: 200 } }],
    edges: [...],
    viewport: { x: 0, y: 0, zoom: 1 }
  }
}

Node Update​

Nodes are updated when users interact with the node's internal form fields.

Trigger: User edits content via the node's inline form Pattern: Blur-based commit (changes commit when field loses focus)

Mutation Impact:

  • Creates an UPDATE command with the changed data
  • Multiple updates to the same field aggregate to a single mutation on save

Node Deletion​

Nodes can be deleted by selecting the node and pressing the Delete key.

Cascade Behavior:

  • All connected edges are automatically deleted
  • If deleting a Question, its Answer relationships are cleaned up
  • If deleting a Category, Answer category references are cleared

Edge Operations​

Edge Creation​

Edges are created in two ways:

  1. Automatically - When new nodes are added, edges connect them to logical parents
  2. Manually - User drags from one node's handle to another

Implied Mutations:

  • Creating an edge between Question and Answer sets the Answer's question_id
  • Creating an edge between Category and Answer sets the Answer's category_id

Edge Selection​

Edges can be selected by clicking on them. Like node selection, this is UI-only state.

Edge Movement​

Edges cannot be moved directly. They are automatically positioned based on their source and target nodes.

Edge Update​

Edges cannot be updated directly. Their visual appearance and routing are derived from node positions.

info

Edges in SERVICE_SELECTION subgraphs are structural - they define parent-child relationships that are persisted as entity references, not as edge entities.

Edge Deletion​

Edges can be deleted by selecting and pressing Delete.

Mutation Impact:

  • Removes the relationship from connected entities
  • If the edge represented a parent reference (e.g., Question→Answer), the child entity's reference is cleared

Summary Table​

InteractionCreates Command?Affects Entity Data?Affects Canvas Data?
Node Creation✅ Yes✅ Yes✅ Yes
Node Selection❌ No❌ No❌ No
Node Movement❌ No❌ No✅ Yes
Node Update✅ Yes✅ Yes❌ No
Node Deletion✅ Yes✅ Yes✅ Yes
Edge Creation✅ Yes (implied)✅ Yes✅ Yes
Edge Selection❌ No❌ No❌ No
Edge Deletion✅ Yes (implied)✅ Yes✅ Yes