# Nodes

Nodes are the visual elements on the canvas that represent workflow components.
Each node has a type, a label, and optional configuration.

## Node types

### Event nodes (start)

Event nodes are the **entry points** of a workflow. They define what triggers
the workflow to execute.

- **Visual style**: Rounded rectangle with a distinct color.
- **Examples**: "Entity is created", "Cron runs", "Form is submitted".
- **Behavior**: A workflow can have multiple event nodes, creating separate
  flows on the same canvas.

![Event node on the canvas](../assets/screenshots/event-node.png){ .screenshot }

### Element nodes (actions)

Element nodes represent **actions** -- tasks that the workflow performs when
executed.

- **Visual style**: Standard rectangle.
- **Examples**: "Send email", "Set field value", "Create entity".
- **Behavior**: Actions execute in the order defined by the edges connecting
  them.

### Gateway nodes

Gateways are **decision points** that control how the workflow branches. They
evaluate conditions and route execution accordingly.

- **Visual style**: Diamond shape.
- **Behavior**: Gateways can split a single flow into multiple paths or merge
  multiple paths back together.

### Subprocess nodes

Subprocess nodes **reference other workflow models**, allowing you to reuse
existing workflows as building blocks.

- **Visual style**: Double-bordered rectangle.
- **Behavior**: When execution reaches a subprocess node, the referenced
  workflow is invoked.

## Common operations

### Selecting a node

Click on a node to select it. The Property Panel opens with the node's
configuration.

### Moving a node

Click and drag a node to reposition it. Nodes snap to a 20px grid.

### Configuring a node

With a node selected, use the Property Panel to:

1. Edit the **label** (click the label text).
2. Fill in the **configuration form** fields.
3. Add an **annotation** for documentation.

### Deleting a node

Select a node and press `Delete`, or use the delete option in the Property
Panel. Deleting a node also removes all edges connected to it.

### Locking a node

Toggle the lock icon in the Property Panel to prevent accidental changes.
Locked nodes cannot be moved, edited, or deleted.

## Quick-add successor

Hover over any node to reveal a **+** button. Click it to open a popup with
components that can follow this node. Select one, and a new node is
automatically placed and connected.

The quick-add popup respects:

- **Context filtering**: Only shows components valid for the selected context.
- **Dependency rules**: Hides components that require predecessor types not
  present in the workflow.
- **Search threshold**: When fewer than 15 components are available, the search
  field is hidden for simplicity.
