app/docs/interface/flow-editor.md

# The flow editor

Build a flow by naming its messages and configuring its nodes. Fluksio draws
the connections and arranges the canvas for you.

## The canvas

The graph runs left to right on desktop and top to bottom on phones. On a
phone, at most two nodes sit side by side and the rest wrap onto the rows
below, so a large flow grows downwards in one column.

- **Nodes** show their execution status.
- **Edges** are routed around the nodes, a loop back to an earlier node
  included, and pulse when values pass through. Click one to inspect its
  payload.
- **Endpoints** show flow inputs, dashboard widgets and nodes in other flows
  that exchange messages with this flow. A value passing lights
  one up in a sweep: left to right when it sends into the flow, right to left
  when it reads out of it.
- **Clicking an endpoint** shows a flow input's type, starting value and
  current value, with a pencil that opens the flow settings to edit it. A node
  in another flow opens that flow on the label leading back here, with its
  edges highlighted.

Values update over a websocket. A connection banner tells you when the editor
cannot reach the engine.

## Adding a node

Choose **Add node** in the bottom dock, or use ⌘P / Ctrl-P. The command palette
also jumps between flows and offers reusable nodes. Select a type to add it
and open its settings.

## The node panel

**Consumes** and **Provides** declare the node's ports. Each has a bound
message, a port name, a payload type and a delivery interval. Outputs also have
a streaming toggle.

A row reads top to bottom, from where a value starts to where it ends. An
input starts as a message and arrives in your code as an argument, so the
message is on top and the argument below it (*as* `prompt`). An output starts
as a key of what your code returns and ends as a message, so the key is on top.

A **Device** node stands for a paired device instead: pick the device, then
its ports under **Publishes** (the device's port, then the message) and
**Follows** (the message, then the port it drives; see
[the device's own ports](dashboards.md#the-devices-own-ports)). A device that
reports its ports offers them in a list with their type filled in and a form
for the settings each one reads, and the command palette offers each one as a
shortcut, such as *Hallway camera*.

Message fields suggest existing names. Matching an output's message is how
you connect an input.

A port name follows the message's last segment (`home.outdoor` becomes
`outdoor`) until you name it. While it follows, it is shown as muted text, and
the pencil beside it opens a field. A field only appears on its own when the
name differs from the message. Set a port name to keep the argument name fixed
while changing its message binding. Names use letters, digits and `_`, cannot
start with a digit, and must be unique among the node's inputs or outputs. Two
messages that end in the same segment, such as `a.level` and `b.level`, get a
warning until one of them is named differently.

Renaming an output's message updates its consumers in the flow. Changing an
input binding points that input at a different message.

### Settings

Built-in nodes show forms for their configuration. Credential fields offer
stored [secrets](operations.md#secrets). JSON settings open a larger editor
and save only when the value parses.

Function nodes also let you add settings passed as arguments alongside the
ports. See [Where a node's values come from](../concepts/values.md).

**Timeout** on a Function node limits silence, not total duration. A node
yielding regularly can run longer than its timeout. Empty or `0` means no
limit, the default.

**Resources** selects a shared worker pool, a named flavor or custom CPU,
memory and GPU requirements. Placement by `worker` and `worker_policy` is
configured through the API or flow JSON; see [Remote workers](../code/workers.md).

### Code and reuse

Define `process(...)` in **Code**. If the file instead contains exactly one
public function, Fluksio uses that function.

Code saves as you type. ⌘S / Ctrl-S in the code editor saves immediately;
**Publish** applies ordinary node code to the running flow. Generated code
from `fluksio sync` is read-only: edit its source repository and sync again.

Only superusers can add or edit code-running nodes. Other users can read code
and configure permitted built-in nodes.

**Reuse** shares node code as a library entry. Saving shared code takes effect
immediately in every flow using it, so check its users before changing it.

## The flow panel

Open **Flow settings** from the pencil button in the dock.

| Setting | Purpose |
|---|---|
| **Running** | starts or stops the published live flow's subscriptions, schedules and webhooks |
| **Mode** | chooses continuous `live` operation or requested `batch` runs |
| **Inputs** | declares external messages, their starting values and whether a run or a panel writes them; run inputs become run parameters |
| **Result** | selects batch output messages |
| **Contents** | shows the node count and message namespace |

For live inputs, **Publish this value now** sends the starting value immediately.
Changing a stored starting value alone does not replace an existing message.

## Inspecting an edge

Click an edge to see its latest payload, timestamp and recent numeric history.
Republish its value from the producer to run downstream nodes without waiting
for the next sensor reading.

## The dock

| Control | Action |
|---|---|
| **Add node** | opens the command palette |
| **Fit to screen** | fits the graph; desktop only |
| **Run** | executes the current live flow once; for batch flows, asks for run parameters |
| **Pause / Resume** | holds or releases pending work while values still arrive |
| **Step** | releases one held item while paused |
| **Flow settings** | opens the flow panel |
| **Publish** | puts the saved draft live |
| **Discard** | removes unpublished changes |
| **Issues** | lists problems by node |
| **Logs** | shows filterable node output |

**Run** uses the current draft when one exists without publishing it. It
executes real node code, including device and network actions. To try a single
value in a live flow, publish it from a flow input or edge inspector.

Pause and step are useful for inspecting held work. They do not make a draft
run a simulation.

## Shortcuts

Use ⌘ on macOS and Ctrl elsewhere.

| Shortcut | Action |
|---|---|
| ⌘P / Ctrl-P | command palette |
| ⌘S / Ctrl-S | publish the flow; inside the code editor, save code |
| ⌘Z / Ctrl-Z | undo a graph edit |
| ⌘⇧Z / Ctrl-Shift-Z | redo a graph edit |
| ⌘C / Ctrl-C | copy selected nodes |
| ⌘V / Ctrl-V | paste nodes, including into another flow |

Text fields and the code editor keep their own undo and clipboard behavior.

## Drafts, conflicts and issues

Edits are saved as drafts. The engine keeps running the published version until
you publish; shared code follows the exception above. **Discard** returns to
the published version. Delete a never-published flow to remove it.

If another editor saved the same flow, a stale save or publish returns a
conflict. Reload and review their changes before retrying.

The canvas reports unconnected inputs, missing starting values, cycles and
code-load errors. These prevent the affected flow from running. Unauthenticated
webhooks are advisory; runtime node-health problems clear when the node
recovers. A degraded node, such as a device node whose device is offline, is
marked amber: it is a warning, and the flow keeps running. See [Flow issues](../concepts/flows.md#when-a-flow-needs-attention).

## See also

- [Flows, nodes and messages](../concepts/flows.md)
- [Node types](../reference/node-types.md)
- [Writing node code](../code/nodes.md)