Flow¶
This page builds the intuition behind every FlowDrop workflow. We start from a single shell command you already know and grow it, one step at a time, into the vocabulary FlowDrop uses: process, graph, node, edge, port, and configuration.
You'll learn:
- Why a workflow is a graph of connected steps
- What a node and an edge are, and why they're separate things
- What ports add on top of edges
- How configuration differs from runtime input
Once these clicks, the formal terminology in the FlowDrop Vocabulary will read as a recap rather than a wall of new words.
1. From command to process¶
Most things you run on a computer fit a simple shape: you give it something, it does work, you see a result.
❯ capitalize "Hello World!"
❯ HELLO WORLD!
Three roles in this command:
| Item | Role | Function |
|---|---|---|
capitalize |
Process | Runs a task on request |
"Hello World!" |
Input | What the process operates on |
HELLO WORLD! |
Output | What the user sees |
┌──────────┐ ┌─────────┐ ┌─────────┐
│ Input │─────▶│ Process │──────▶│ Output │
└──────────┘ └─────────┘ └─────────┘
The same shape shows up everywhere:
-
A math function:
x ─▶ f(x) ─▶ y -
A computer:
┌──────────┐ ┌─────────┐ ┌─────────┐ │ Keyboard │─────▶│Processor│──────▶│ Monitor │ └──────────┘ └─────────┘ └─────────┘
A FlowDrop workflow is built from this same shape, repeated and connected.
2. A process without user input¶
Some processes don't need anything from the user — you invoke them and they produce a result.
❯ date
❯ Tue Apr 28 13:27:37 CEST 2026
┌──────────┐ ┌─────────┐ ┌─────────┐
│ Get Date │─────▶│ Clock │──────▶│ Display │
└──────────┘ └─────────┘ └─────────┘
You typed date with no arguments — from your perspective, no input was required. But something still set the process in motion. The act of invoking date is a trigger: a signal that says "run now". Get Date plays that role here — the arrow into Clock doesn't carry a value, it just fires the process. Clock reads the system time on its own and hands the result to Display.
Notice this: not every arrow in a graph carries data. Some arrows just trigger the next step. We'll come back to this distinction in the next tutorial, where we separate trigger edges from data edges.
Keep Get Date and Clock in mind — they'll keep appearing as we add more inputs.
3. Multiple inputs¶
Now we combine the no-input process from Chapter 2 with a user-supplied value:
❯ date +%Y
❯ 2026
+%Y is a format string the user provides. The process needs both the current date and the format to produce its output:
┌──────────┐
│ Format │───┐ ┌─────────┐
└──────────┘ └──▶ │ ┌─────────┐
│ Clock │──────▶│ Display │
┌──────────┐ ┌──▶ │ └─────────┘
│ Get Date │───┘ └─────────┘
└──────────┘
Two arrows now feed into Clock, and they're not the same kind. Get Date is still the trigger from Chapter 2 — it tells Clock to run but carries no value. Format is different: it carries the actual format string +%Y into the process. One arrow triggers, the other delivers data, and a single process can take any mix of the two.
4. Configuration vs. runtime input¶
What if some inputs are settings you decide once when building the workflow, rather than values that arrive each time it runs?
# Set the system wide default for timezone.
❯ set TZ="Asia/Tokyo"
❯ date
❯ Tue Apr 28 20:34:42 JST 2026
# Override system wide defualt timezone during runtime.
❯ date -z "CET"
❯ Tue Apr 28 13:34:47 CEST 2026
Same date command, different output — because TZ was set as an environment variable, not passed as an argument. It's part of how the process is configured to run, not data that flows in for this particular invocation.
We draw this kind of value inside the process box to mark it as configuration:
┌──────────┐ ┌────────────────────────┐
│ TimeZone │──────▶ Clock │
└──────────┘ │ │
│ │
│ │ ┌─────────┐
│ ┌──────────────┐ │───▶│ Display │
│ │ TimeZone │ │ └─────────┘
│ ├──────────────┤ │
┌──────────┐ │ │ Format │ │
│ Get Date │──────▶ └──────────────┘ │
└──────────┘ └────────────────────────┘
Notice TimeZone appears twice: once as an outside arrow (a runtime input that could change each run) and once inside Clock (a configured default). The same logical concept can be either, depending on how the workflow is wired. We'll come back to this distinction in Chapter 7.
5. Graphs: nodes and edges¶
We've been drawing the same shape — boxes connected by arrows — for four chapters. That shape has a name: a graph.
Here's the diagram from Chapter 4 with the date-specific labels stripped away:
┌──────────┐ ┌────────────────────────┐
│ Node 1 │───Edge 1─────▶ │
└──────────┘ │ │
│ │
│ │ ┌─────────┐
│ Node 3 │──Edge 3───▶│ Node 4 │
│ │ └─────────┘
│ │
┌──────────┐ │ │
│ Node 2 │───Edge 2─────▶ │
└──────────┘ └────────────────────────┘
The graph has 4 nodes and 3 edges.
- A node is a step — a process box.
- An edge is a connection between two nodes — an arrow.
Nodes are places; edges are one-way streets. Nodes describe what happens; edges describe which step feeds which.
A FlowDrop workflow is exactly this: a graph of nodes connected by edges.
6. Ports: typed connection points¶
Edges don't attach to nodes anywhere — they attach at specific spots called ports.
- Input ports sit on the left of a node. They're where incoming edges land.
- Output ports sit on the right. They're where outgoing edges leave.
┌───────────────────────────────────┐
├──────────────┐ │
───Edge 1─────▶│ Input Port 1 │ │
├──────────────┘ │
│ │
│ Node 3 │
│ │
├──────────────┐ ┌──────────────┤
────Edge 2────▶│ Input Port 2 │ │Output Port 2 ├───Edge 3───▶
├──────────────┘ └──────────────┤
└───────────────────────────────────┘
Why bother naming ports separately from edges? Because ports are typed: a port that expects a number won't accept an edge carrying text. The type system catches mistakes when you build the workflow rather than when it runs.
In the visual editor, ports are colour-coded by data type — string, number, boolean, date, file, and so on. See the full type table in FlowDrop Vocabulary › Ports.
7. Static configuration on a node¶
We hinted at this in Chapter 4: not every value needs to flow in through an edge. Some values are decided once when you build the workflow and stay put. Those are stored as configuration directly on the node.
┌────────────────────────┐
───Edge 1─────▶ Node 3 │
│ │
│ │
│ │
│ ┌──────────────┐ │──Edge 3───▶
│ │ TimeZone │ │
│ ├──────────────┤ │
│ │ Format │ │
───Edge 2─────▶ └──────────────┘ │
└────────────────────────┘
The inner boxes you saw all along — TimeZone, Format — are the node's configuration. The distinction matters:
- Ports carry dynamic values. They're computed every time the workflow runs, by upstream nodes.
- Configuration holds static values. You set them once in the editor; they don't change between runs.
When you design a workflow, deciding what should be a port versus what should be configuration shapes how reusable the node is. A TimeZone configured on the node fixes that workflow to one zone. The same TimeZone exposed as a port lets each run pick its own.
Recap¶
| Term | Meaning |
|---|---|
| Process | A step that turns inputs into outputs |
| Graph | A set of processes connected by arrows |
| Node | A single step in the graph |
| Edge | A one-way connection between two nodes |
| Port | A typed connection point on a node where an edge attaches |
| Configuration | Static values set on a node when the workflow is built |
Next steps¶
- Read the FlowDrop Vocabulary for FlowDrop-specific details (data edges vs. trigger edges, the full port type table, execution order).
- Build something: Your First Workflow.