Canvas & Interaction

The Fluxion canvas is an infinite 2D workspace rendered with Canvas2D. It supports panning, zooming, node dragging, pin connections, multi-selection, and context menus.

Navigation

Action	Input	Description
Pan	Middle mouse button + drag	Move the viewport around the canvas
Pan (alt)	Alt + left click + drag	Alternative panning method
Zoom	Scroll wheel	Zoom in/out centered on cursor (0.1x to 4x)
Fit View	Toolbar ⊞ Fit	Auto-zoom and pan to fit all nodes

Working with Nodes

Adding Nodes

Right-click anywhere on the canvas to open the context menu. All available node types for the current module are listed with icons and labels. Click to place at the cursor position.

Selecting & Moving

Action	Input	Result
Select	Left click on node	Highlights node with dashed selection ring, opens Inspector
Drag	Click + hold + drag (>5px)	Repositions the node
Box Select	Left click + drag on empty space	Draws selection rectangle; all nodes inside are selected (live preview)
Multi-Drag	With multiple selected, drag any one	Moves all selected nodes together
Deselect	Click empty canvas	Clears selection, closes Inspector
Delete	Delete or Backspace	Removes selected nodes/connections
Nudge	↑ ↓ ← →	Moves selected nodes by grid size or nudge amount
Collapse	Double-click node header	Toggles node between full and collapsed (header-only) view
Undo	Ctrl+Z	Reverts last action (up to 50 steps). Works for add/delete/move/connect/config changes
Copy	Ctrl+C	Copies selected nodes and their internal connections to clipboard
Paste	Ctrl+V	Pastes copied nodes at +40px offset with new IDs. Repeated paste stacks further

Multi-Node Context Menu

When multiple nodes are selected, right-click to open a special context menu:

• Delete Selected — Removes all selected nodes and their connections
• Straighten — Aligns nodes horizontally at average Y position with even spacing, sorted left-to-right

Connecting Nodes

Each node has input pins (left) and output pins (right). To create a connection:

1. Hover over an output pin — cursor changes to crosshair
2. Click and drag — a dashed bezier wire follows your cursor
3. Release on an input pin — connection is created

Connected pins show a filled green dot. Unconnected pins show an empty circle.

Deleting Connections

Click on a connection wire to select it (turns red with pulsing glow), then press Delete or Backspace.

Hover & Tooltips

Hovering over a connection after execution shows a floating tooltip with the upstream node's output data as formatted JSON.

Inspector Panel

The Inspector slides in from the right when you click a node. Two tabs:

Config Tab

• Label — Editable display name
• Type badge — Read-only node type indicator
• Type-specific fields — Varies by node type
• Save Config — Applies changes and regenerates the processor

For list-based config (validation rules, transform mappings, events, actions), use + Add to add entries and × to remove them.

Data Tab

Available after execution. Shows:

• Duration — Processing time in milliseconds
• Diff View — Color-coded comparison: + Added, − Removed, ~ Changed, Unchanged
• Input JSON — Full data entering the node
• Output JSON — Full data leaving the node

Visual Effects

• Grid Background — Subtle grid that scrolls with the viewport
• Node Glow — Active/processing nodes emit a pulsing glow
• Ripple Effects — Green on entry, yellow for slow nodes (>500ms), red shockwave on errors
• Flow Particles — Animated dots along active connections
• Data Packet — Glowing orb with "N fields" badge traveling between nodes (visible in all modules: API, State Machine, and Database)
• Processing Spinner — Circular indicator on the node header while processing
• Canvas Data Overlay — Live diff panel next to the currently processing node
• Empty Canvas Placeholder — Instructions shown when canvas has no nodes
• Grid Highlight on Drag — Colored grid lines glow around nodes while dragging
• Minimap — Bottom-right overview panel showing all nodes and viewport position

Comment Boxes

Comment boxes let you visually group and annotate regions of your canvas, inspired by UE5 Blueprint comment nodes.

Creating Comment Boxes

Right-click on empty canvas space and select Add Comment Box from the context menu. A 300×200 box appears at the cursor position with a default "Comment" label.

Interacting with Comment Boxes

Action	Input	Result
Select	Left click on comment box	Selects the comment box (blue dashed border)
Move	Click + drag	Moves the comment box AND all nodes whose center falls inside it
Resize	Drag corner or edge handles	Resizes the box (minimum 100×60px)
Edit Label	Double-click header	Opens a prompt to rename the comment box
Delete	Delete or Backspace	Removes the comment box (nodes inside are kept)

Connection Reroute Points

Reroute points let you reshape connection wires by inserting draggable waypoints, similar to UE5 Blueprint reroute nodes.

Adding Reroute Points

Double-click on any connection wire to insert a diamond-shaped reroute point at that position. The connection is split into segments that route through the reroute point.

Managing Reroute Points

Action	Input	Result
Add	Double-click a connection wire	Inserts a diamond reroute point at cursor position
Move	Click + drag the diamond	Repositions the reroute point (respects snap-to-grid)
Select	Click the diamond	Selects it (white outline)
Delete	Delete while selected	Removes the reroute point; wire reconnects directly

Multiple reroute points can be added to a single connection. The wire segments use bezier curves between consecutive points, maintaining smooth paths. Flow particles animate along the full chain during execution.

Node Collapse

Double-click a node header to collapse it to a compact header-only view. This reduces visual clutter for nodes you don't need to inspect frequently.

• Collapsed nodes show only the header bar with a ▸ indicator
• All connections are preserved — input pins route to the left center edge, output pins to the right center edge
• Double-click the header again to expand back to full size
• Collapsed state persists through save/load

Minimap

A 200×140px overview panel in the bottom-right corner provides a bird's-eye view of your entire graph.

• Each node appears as a small colored rectangle using its theme accent color
• Comment boxes appear as semi-transparent rectangles
• A bright outline rectangle shows your current viewport position
• Click anywhere on the minimap to instantly pan the canvas to that position
• Drag on the minimap for continuous panning
• Can be toggled off in Settings (Canvas tab)

Grid Highlight on Drag

When you drag one or more nodes, the grid cells around the dragged nodes illuminate with a subtle colored highlight. This provides spatial context and makes alignment easier.

• The highlight extends one grid cell beyond the node bounding box in each direction
• Only visible when the grid is enabled and nodes are being dragged
• Adapts to light/dark theme
• Can be toggled off in Settings (Canvas tab)

Arrow Key Nudging

Move selected nodes precisely using keyboard arrow keys:

Key	Action
↑	Move selected nodes up
↓	Move selected nodes down
←	Move selected nodes left
→	Move selected nodes right

When snap-to-grid is enabled, nodes nudge by the grid size. Otherwise, they nudge by a configurable pixel amount (default 10px). Both the nudge toggle and nudge amount are configurable in Settings.

Settings Modal

Click the cogwheel icon in the left sidebar to open the Settings modal. Settings are organized into three tabs:

General Tab

Setting	Description	Default
Theme	Dark or Light mode	Dark
Default Speed	Execution animation speed (0.05x – 3.0x)	1.0x
Auto Save	Automatically save the graph at regular intervals	Off
Auto Save Interval	Seconds between auto-saves	30s

Canvas Tab

Setting	Description	Default
Show Grid	Display background grid	On
Grid Highlight on Drag	Glow grid cells around nodes while dragging	On
Snap to Grid	Snap node positions to grid intersections	Off
Grid Size	Grid cell size in pixels	20px
Arrow Key Nudging	Enable moving nodes with arrow keys	On
Nudge Amount	Pixels to move per arrow key press (when snap-to-grid is off)	10px
Show Particles	Animated flow particles on connections	On
Show Ripples	Node processing ripple effects	On
Show Data Overlay	Live diff panel next to processing nodes	On
Show Minimap	Overview panel in bottom-right corner	On
Line Thickness	Connection wire thickness — increase for better visibility in Light mode. Options: 1px (Thin), 1.5px (Default), 2.5px (Medium), 3.5px (Thick)	1.5px

Storage Tab

• Per-module size bars — Visual indicator of localStorage usage for each module
• Clear All — Removes all saved graphs from localStorage
• Export All — Downloads all saved graphs as JSON files

API Node Types

The API module has 12 node types covering every stage of a typical API request lifecycle.

Input

Defines the API entry point. Always the first node in a pipeline.

Field	Description	Default
Method	HTTP method (GET, POST, PUT, PATCH, DELETE)	POST
Path	API route path	/api/endpoint
Body	Key-value pairs defining initial request data	email, password, name, Authorization

Processing: Adds _method, _path, _receivedAt. The Body key-value pairs become the initial data packet.

Validation

Enforces field constraints. Throws an error if any rule fails.

Rule Field	Description
Field Name	The data field to validate
Type	string, number, email, boolean, or any
Required	Whether the field must be present
Min / Max	Min/max length or value

Pins: valid (success) and invalid (error path).

Authentication

Simulates authentication checks.

Field	Description	Default
Auth Type	bearer, api-key, or basic	bearer
Header Name	Which header carries the credential	Authorization

Pins: authenticated and denied.

Transform

Field-level data transformations via configurable mappings.

Mapping	Description
From / To	Source and target field names
Transform	none, rename, lowercase, uppercase, trim, hash, delete

Enrichment

Adds computed or lookup data. Config: Source name + key-value pairs to inject.

Database

Simulates a database operation (select, insert, update, delete). Config: Operation, Table, Fields.

Pins: result and error.

External API

Simulates calling a remote HTTP service. Config: URL, Method, Headers.

Pins: response and error.

Condition

Branches flow based on a field comparison. Config: Field, Operator (==, !=, >, <, exists, truthy), Value.

Pins: true and false.

Response

HTTP response node. Config: Status Code, Headers (key-value pairs). Typically the last node.

Error Handler

Handles errors from upstream nodes. Config: Error Type, Message, Status Code.

Middleware

Cross-cutting concerns. Config: Type (logging, rate-limit, cors, custom), Config text.

Delay

Introduces artificial processing delay. Config: Delay in milliseconds (default 1000).

State Machine Module

The State Machine module lets you visually design, execute, and export finite state machines. Switch to it via the ◇ SM tab in the left sidebar. State machines support cyclic transitions, making them ideal for modeling traffic lights, door locks, UI flows, and more.

SM Node Types

8 node types are available in the State Machine module:

Initial (●)

The entry point. Defines machine name, event queue, and initial context.

Field	Description	Default
Machine Name	Identifier for the machine	myMachine
Initial Context	Key-value pairs for initial context data	—
Events	Ordered list of events to process	EVENT_1, EVENT_2

State (□)

Represents a state. Can have entry/exit actions and configurable event slots.

Field	Description
State Name	Display name
Event Slots	Number of outgoing transition slots (output pins)
Entry Actions	Actions on entering (e.g., startTimer)
Exit Actions	Actions on leaving (e.g., stopTimer)

Transition (→)

Connects states. Triggered by matching events.

Field	Description
Event	Event name that triggers this transition
Guard	Optional condition expression
Action	Optional action name to execute

Final (◉)

Marks the end of the machine. Execution stops when reached.

Choice (◇)

Branching node that evaluates guard conditions.

Pins: if-true and if-false.

Guard

Standalone guard that evaluates a condition expression.

Pins: pass and fail.

Action (⚡)

Executes a side-effect (assign, send, log, custom).

Pins: Single done output.

Parallel (║)

Represents parallel state regions. Config: number of regions (output pins).

SM Execution

State Machine execution is event-driven:

1. Find the sm-initial node, read event queue and initial context
2. Follow connection to the first sm-state
3. For each event in the queue:
   • Find outgoing sm-transition nodes matching the event name
   • If a transition has a guard, evaluate it; skip if false
   • First matching transition fires, its action executes
   • Follow transition output to the next state
   • If no transition matches, stay in current state
4. If sm-final is reached, execution stops
5. If all events consumed, execution completes at current state

Guards & Conditions

Guard expressions support:

• true / false — Literal boolean
• fieldName — Truthy check on a context field
• field == value — Equality comparison
• field != value — Inequality comparison

SM Export Formats

XState v5

Generates a createMachine() definition for XState v5 with states, transitions, guards, and actions.

TypeScript Class

Standalone class with State/Event type unions, transition table, guard functions, send(event) method, and entry/exit action support.

Mermaid Diagram

Generates stateDiagram-v2 for rendering in Mermaid-compatible tools (GitHub, docs sites, etc.).

Fluxion JSON

Same portable JSON format as the API module for round-trip import/export.

Database Module

The Database module lets you visually design schemas, compose queries, build CRUD pipelines, and export real SQL or Prisma code. Switch to it via the ◫ DB tab in the left sidebar. Supports both SQL (PostgreSQL, MySQL) and NoSQL (MongoDB) — the same nodes adapt based on the database type configured in the Source node.

DB Node Types

12 node types are available in the Database module:

Source (◈)

The entry point. Defines the database connection and type. Always the first node in a database pipeline.

Field	Description	Default
DB Type	Database engine: postgresql, mysql, sqlite, mongodb	postgresql
Connection String	Connection URI	postgresql://localhost:5432/mydb
Database Name	Target database name	mydb
Options	Key-value connection options (pool size, SSL, etc.)	—

Processing: Sets _dbType, _dbConnection, _dbName, initializes _dbTables registry and _dbRelations array.

Table (▣)

Defines a table (SQL) or collection (NoSQL) schema. Every column is registered for downstream validation.

Field	Description
Table Name	Name of the table or collection
Engine	Storage engine (InnoDB, MyISAM, etc.)
Columns	Dynamic list — each entry has Name, Type, Constraint (PRIMARY KEY, UNIQUE, NOT NULL, DEFAULT, REFERENCES), and Nullable toggle

Column types (SQL): SERIAL, INTEGER, BIGINT, VARCHAR(N), TEXT, BOOLEAN, TIMESTAMP, DATE, DECIMAL, JSON, UUID

Column types (NoSQL): String, Number, ObjectId, Date, Boolean, Array, Object

Pins: created (success) and error (validation failure).

Relation (↭)

Defines a foreign key relationship between two tables.

Field	Description
From Table / Column	Source side of the relationship
To Table / Column	Target side of the relationship
Relation Type	one-to-one, one-to-many, many-to-many
ON DELETE / ON UPDATE	CASCADE, SET NULL, RESTRICT, NO ACTION

Processing: Validates both tables exist in _dbTables. Pushes relationship to _dbRelations array. Throws if either table is undefined.

Query (🔎)

SELECT query. Builds real SQL from config and validates fields against the table schema.

Field	Description	Default
Table	Target table to query	—
Fields	Comma-separated column list (or *)	*
Distinct	SELECT DISTINCT toggle	false
Limit	Maximum rows to return	—
Offset	Rows to skip	—

Pins: rows (results found) and empty (zero rows matched).

Insert (✚)

INSERT operation. Validates fields exist in the table schema.

Field	Description
Table	Target table
Fields	Comma-separated column names to insert
Returning	Columns to return after insert (RETURNING clause)
On Conflict	Conflict resolution strategy (ignore, update, error)

Pins: inserted (success) and error (validation/conflict failure).

Update (✎)

UPDATE operation. Sets specific fields with optional WHERE clause.

Field	Description
Table	Target table
SET Fields	Comma-separated column = value pairs
WHERE	Filter condition
Returning	Columns to return after update

Pins: updated (success) and error (failure).

Delete (✕)

DELETE operation with optional soft-delete support.

Field	Description
Table	Target table
WHERE	Filter condition
Cascade	Whether to cascade to related records
Soft Delete	Uses SET deleted_at = NOW() instead of actual deletion

Pins: deleted (success) and error (failure).

Join (⋈)

JOIN operation between two tables.

Field	Description
Join Type	INNER, LEFT, RIGHT, FULL, CROSS
Right Table	Table to join with
ON Left / ON Right	Join condition columns
Select Fields	Which columns to include from joined result

Processing: Validates both tables exist. Builds JOIN SQL fragment. Merges column data from both tables.

Where (⚙)

Filtering, ordering, and grouping. Attaches to the upstream query node.

Field	Description
Conditions	Dynamic list — each entry has Field, Operator (=, !=, >, <, >=, <=, LIKE, IN, IS NULL, IS NOT NULL), Value, and Conjunction (AND/OR)
ORDER BY	Column to sort by
Order Direction	ASC or DESC
GROUP BY	Column to group by

Processing: Every condition in the list is read and applied. All operators produce real SQL clauses.

Aggregate (Σ)

GROUP BY with aggregate functions.

Field	Description
Table	Target table
Group By	Column to group by
Aggregations	Dynamic list — each entry has Function (COUNT, SUM, AVG, MIN, MAX), Field, and Alias
Having	HAVING clause for filtering aggregated results

Transaction (🔒)

Wraps downstream operations in a database transaction.

Field	Description	Default
Isolation Level	READ COMMITTED, REPEATABLE READ, SERIALIZABLE	READ COMMITTED
Auto Rollback	Automatically rollback on any error	true

Pins: commit (all downstream succeeded) and rollback (any downstream failed).

Result (■)

Terminal output node. Displays the final pipeline data.

Field	Description	Default
Format	Output format: json, table, csv	json
Label	Display label for the result	Query Result

DB Execution

Database execution follows a sequential pipeline model:

1. Find the db-source node, read connection config and options
2. Follow connections sequentially — each node receives the output of the previous node
3. At each node, the processor:
   • Reads all config fields from the inspector form
   • Validates references (table names, column names) against the runtime schema registry
   • Builds real SQL strings (stored in _dbQuery for inspection)
   • Transforms the data packet and passes it downstream
4. Branching: Nodes with dual output pins route based on success/failure:
   • Error pins fire when a processor throws (invalid table, missing column, constraint violation)
   • Query empty pin fires when zero rows are returned
   • Transaction rollback pin fires when any downstream node errors
5. Execution completes at a db-result node or when no more connections exist

Schema Validation

The Database module performs real validation at execution time:

• Table existence — Query, Insert, Update, and Delete nodes check their target table is defined in _dbTables. If not, they throw a descriptive error listing available tables.
• Column existence — SELECT fields are validated against the table's column definitions. Referencing a non-existent column throws an error listing valid columns.
• Relation validation — The Relation node checks both tables exist before creating a foreign key.
• Empty column names — Table node rejects columns with blank names.

DB Export Formats

SQL (DDL + DML)

Generates complete, usable SQL from your pipeline. Every config field is reflected in the output:

• CREATE TABLE — With all columns, types, constraints, and nullability
• ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY — With ON DELETE/ON UPDATE actions
• SELECT — With DISTINCT, fields, LIMIT, OFFSET, WHERE, ORDER BY, GROUP BY
• JOIN — Attached to the SELECT with correct join type and ON clause
• INSERT INTO — With parameterized values and RETURNING clause
• UPDATE — With SET fields, WHERE clause, and RETURNING
• DELETE FROM — With WHERE clause; soft delete uses SET deleted_at = NOW()
• BEGIN / COMMIT — Wraps transaction body with isolation level
• Aggregate — Full SELECT groupBy, FN(field) AS alias GROUP BY ... HAVING ...

Prisma Schema

Generates a valid Prisma schema file with:

• datasource db with provider and connection URL from Source config
• model blocks for each Table node with field types, @id, @unique, @default
• @relation directives from Relation nodes with references and fields
• Proper Prisma type mapping (SERIAL → Int @id @default(autoincrement()), UUID → String @default(uuid()), etc.)

Mermaid ER Diagram

Generates erDiagram syntax for Mermaid-compatible tools with:

• Entity blocks with column names, types, and constraint annotations (PK, FK, UK)
• Relationship lines with correct cardinality (||--o{, ||--||, }o--o{)

Fluxion JSON

Same portable JSON format as the other modules for round-trip import/export.

SQL vs NoSQL

The Database module is config-driven. The same node types work for both SQL and NoSQL databases — the Source node's dbType field determines the behavior:

Aspect	SQL (PostgreSQL/MySQL)	NoSQL (MongoDB)
Table node	CREATE TABLE with typed columns	Collection with flexible fields
Query output	SELECT ... FROM ...	db.collection.find({...})
Insert output	INSERT INTO ... VALUES ...	db.collection.insertOne({...})
Column types	SERIAL, VARCHAR, INTEGER, etc.	String, Number, ObjectId, etc.
Relations	Foreign keys with constraints	References (application-level)
Transactions	BEGIN / COMMIT / ROLLBACK	session.startTransaction()

Execution & Export

Fluxion's execution engine processes your pipeline by following the connections you've wired, applying each node's processor to a data packet as it flows through the graph.

Toolbar Controls

Button	Description
▶ Run	Execute the flow with sample input data
⏩ Step	Advance to next node (starts in Step mode if not running)
⏸ Pause / ▶ Resume	Pause execution; click again to resume. Icon toggles.
⏹ Stop	Stop execution and reset visual state
Import	Open import modal (paste JSON or load demo)
Export	Open export modal with format tabs
⊞ Fit	Auto-zoom to center all nodes
💾 Save	Save graph to browser localStorage
🗑 Clear	Clear saved graph and reset canvas

Execution Modes

Live Mode

Default mode. Full animation with configurable speed. Each node type has a characteristic delay with ±20% jitter.

Step Mode

Pauses before each node. Click Step to advance. Status shows "Waiting for step..."

Slow-Motion Mode

Like Live but at 0.2x speed (5x slower).

Replay Mode

After execution, scrub through the timeline with a slider.

Speed Control

Slider adjusts speed from 0.05x to 3.0x.

Execution Summary & Log

After execution, a summary banner appears at the bottom of the canvas:

• Green ✓ — Completed successfully
• Yellow ⚠ — Completed with warnings
• Red ✕ — Execution failed

Click ▸ Details to open the Execution Log modal — a step-by-step breakdown with node names, type badges, and context-specific details (guard results, HTTP codes, condition evaluations, error messages).

The banner auto-dismisses after 12 seconds or click ✕ to dismiss.

How API Execution Works

1. Entry Node — Starts at the Input node (or first node with no incoming connections)
2. Packet Creation — Data packet from the Input node's Body key-value pairs
3. Node Processing — Enter node → snapshot input → run processor → snapshot output → compute diff
4. Pin-Based Routing — Branching nodes route to specific output pins (valid/invalid, true/false, result/error)
5. Connection Travel — Animated packet along bezier curve
6. Error Handling — Errors route through error pin; no error route = execution stops
7. Completion — Finishes when no outgoing connection exists

API Export Formats

Express.js

Production-ready Node.js/Express server with route handlers, validation, auth, DB queries, and error handling. ~80% production-ready.

Fluxion JSON

Portable pipeline definition with nodes, connections, pins, and configs. Use to save, share, or re-import.

Pseudocode

Human-readable step-by-step description for documentation and reviews.

Importing

Fluxion JSON

Paste exported JSON to restore any pipeline. Works for API, State Machine, and Database modules.

OpenAPI / Swagger

Paste OpenAPI 3.x or Swagger 2.x JSON. Auto-generates API pipeline with Validation, Auth, Transform, DB, and Response nodes.

Demos

Each module has built-in demos. Click a demo card to instantly load it. API has 2 demos, State Machine has 2, and Database has 4 (User CRUD, Join & Aggregate, Bank Transfer, NoSQL MongoDB).

Save & Persistence

Graphs are stored in browser localStorage with separate slots:

• fluxion_graph_api — Saved API pipeline
• fluxion_graph_sm — Saved State Machine
• fluxion_graph_db — Saved Database pipeline

Saved graphs auto-restore on app load or module switch. Uses the same Fluxion JSON format as export.

Syntax Highlighting

The export modal highlights code:

• Keywords — const, let, function, async, await, return, if, else
• Strings — Single-quoted, double-quoted, template literals
• Numbers
• Comments
• Built-ins — app, res, req, data, db, console

Provides Copy to Clipboard and Download File buttons.