Graphs

Graphs are the core execution unit in Swirls. Each graph is a directed acyclic graph (DAG) of nodes connected by edges. Execution flows through nodes in topological order.

Data model

• Graph: Belongs to a project. Has a name, optional description, and contains nodes and edges.
• Nodes: Building blocks inside the graph. Each node has a type (LLM, HTTP, switch, code, stream, email, scrape, or wait), configuration specific to its type, and optional input/output schemas. Node names must contain only letters, numbers, and underscores.
• Edges: Connect a source node to a target node. Edges define execution order and data flow. Optional labels (for example, yes / no on a switch node's outgoing edges) document which branch is taken.

Execution is deterministic: nodes run in topological order, and parallel branches execute when their inputs are ready.

Root nodes and exit nodes

• Root nodes are nodes with no incoming edges. They serve as entry points for the graph. A trigger (form, webhook, schedule, or agent) can be attached to a root node so that when the trigger fires, the graph executes starting from that node with the trigger payload as input.
• Exit nodes are nodes with no outgoing edges. Execution completes when all exit nodes finish. If a stream is configured for the graph, exit node outputs are persisted to the stream.

Runtime flow

1. A trigger fires (form submission, webhook request, scheduled event, or agent tool call). The trigger is attached to a root node of a graph.
2. The graph execution starts from that root node with the trigger payload as input.
3. Nodes run in topological order. Each node receives data from upstream nodes and the initial payload, then produces output stored in a node execution record. When nodes are connected by edges, the downstream node automatically inherits the upstream node's output schema as its input schema.
4. When all nodes finish (including exit nodes), the graph execution completes. Outputs and errors are recorded for each node and for the overall run.

Streams

A graph can have an associated stream that persists exit node outputs after each execution. Stream schemas are derived from the output schemas of the graph's exit nodes. See Streams for details.

Design tips

• Keep graphs acyclic. Swirls validates that edges do not create cycles. Use switch nodes to branch execution, not to loop back.
• Name nodes clearly. Node names appear in execution logs, the editor, and API responses. Use descriptive names that reflect what each node does.
• Use edge labels. Labels on switch node edges (for example, approved / rejected) make branching logic easier to read and debug.
• Start simple. Begin with a single root node and add complexity as needed. You can always add more nodes and branches later.

Graphs define how data is processed. Triggers on root nodes define when that processing starts. See Nodes for node types, Triggers for trigger configuration, and Schemas for defining data shapes.