# 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](concepts.md) 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.

```cmd
❯ 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:

1. A math function:
```
  x ─▶ f(x) ─▶ y
```

2. 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.

```cmd
❯ 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:

```cmd
❯ 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?

```cmd
❯ TZ="Asia/Tokyo" date
❯ Tue Apr 28 20:34:42 JST 2026
```

```cmd
❯ date
❯ 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](concepts.md#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](concepts.md) for FlowDrop-specific details (data edges vs. trigger edges, the full port type table, execution order).
- Build something: [Your First Workflow](first-workflow.md).
