Skip to main content

How Flows Execute

Understanding how flows execute helps you build more reliable automations.

Execution Flow​

  1. A trigger fires — Something happens (a chat command, a subscription, a timer tick) that activates a trigger node
  2. Forward propagation — The engine walks downstream from the trigger, executing each connected node in order
  3. Data flows through edges — Each node receives data from its inputs, processes it, and sends results to its outputs
  4. Effects execute — When the engine reaches an effect node, it performs the action (sends a message, switches a scene, etc.)

Key Behaviors​

Data Nodes Are Lazy​

Data nodes (Text Data, Number Data, Flow Variable, etc.) don't execute until a downstream node actually requests their value. This means unused data nodes don't waste processing time.

Nodes Can Run Multiple Times​

If a node is connected to multiple upstream paths, it may execute more than once — once for each path that reaches it. This is by design and allows you to reuse nodes across different branches of your flow.

Effects Are Terminal​

Effect nodes have no outputs. They are the end of the line — they perform an action and stop. You can have multiple effect nodes in a single flow, and they'll all execute when their inputs are satisfied.

Check Nodes Branch Execution​

Check nodes have two (or more) outputs. Only one output path will execute based on the check's result. For example, an Is Moderator check will either continue down the "true" path or the "false" path, never both.

Cycle Detection​

Flows cannot have circular connections. If Node A connects to Node B, and Node B connects back to Node A, the editor will prevent you from creating that connection. This prevents infinite loops.

Error Handling​

If a node encounters an error during execution, the flow stops at that point. Downstream nodes will not execute. Check the flow's execution log for details about what went wrong.

Execution Environments​

Not every node runs in the same place. Flows are executed in one of three environments, and each node in the reference is tagged with a Runs on line that tells you which environment(s) it can execute in.

Backend (Streamerly server)​

Most flows run on the Streamerly backend. This environment has full access to:

  • The PostgreSQL database (variables, user records, team memberships)
  • The Twitch Helix API (sending chat messages, modifying channel state, looking up users)
  • The OBS WebSocket bridge (switching scenes, toggling sources and filters)
  • Overlay alert sockets (pushing alerts to OBS browser sources)
  • Redis (cooldown timing, rate limits)

Any node that performs a visible or persistent action — sending chat, banning a user, switching scenes, triggering an alert — is a Backend node and can only run here.

Frontend (Chatbox Flow Editor)​

The Chatbox Flow Editor is a separate flow environment that runs inside the OBS browser source. Instead of reacting to server-side events, it reacts to individual chat messages as they arrive on the client and decides how to render them in the chatbox overlay.

This environment is intentionally sandboxed:

  • It cannot talk to the database, Twitch API, or OBS bridge
  • It only sees the current ChatMessage object
  • Its only terminal effect is Select Variant, which picks a message template variant to render
  • All the chatbox-specific check nodes (is-mod, is-sub, is-cheer, has-message-effect, etc.) read directly from the ChatMessage badges, emotes, and flags without any network calls

Because the chatbox is one example of a frontend flow environment, chatbox-only nodes are grouped under the Frontend (Chatbox) runtime class. Future frontend environments may share this runtime class with additional sub-environments.

Shared​

A large number of nodes are pure logic — math, string manipulation, list operations, boolean checks, regex, template rendering. These nodes have no external dependencies, so the exact same executor code is registered in both the backend and the chatbox frontend. Shared nodes work identically in any environment and can be used freely in both backend flows and chatbox flows.

How to Tell Which Environment a Node Uses​

Every node reference page starts with a blockquote like:

Runs on: Backend — requires the Twitch API to send messages.

Possible values:

  • Backend — Server-side only
  • Shared — Runs on backend and frontend chatbox
  • Frontend (Chatbox) — Chatbox Flow Editor only

The short phrase after the dash explains why the node has that classification (what external dependency it needs, or what data it operates on).

Testing Your Flows​

Use these tools to test and debug:

  • Manual Trigger — Run your flow on demand without waiting for a real event
  • Echo — The Echo effect logs its input to the execution log, letting you inspect data at any point in your flow
  • Run button — Click the Run button in the toolbar to execute the flow immediately