# Concepts

## Steps

A **step** is one function in your worker, defined with `defineStep()` in a file under `src/steps/`. It gets a config, does its work and returns a JSON-serialisable output. Its **slug** (such as `IN1_01_check`) is how stations refer to it. See [Write steps](/docs/workers/write-steps).

## Stations

A **station** is an ordered list of steps with a config for each. It's the unit the Orchestrator runs. A station has a **short code** (`IN1`), belongs to a **line** (`IN`), and can run on a cron schedule or when you trigger it.

You keep stations as JSON files in `.orchestrator/stations/` and push them with fob-orc. See [Stations and lines](/docs/workers/stations-and-lines).

## Lines

A **line** groups the stations of one workflow, such as invoice intake, in order. A line has a **location**: the worker that runs its stations. Stations on a line hand work to each other through bins.

## Work records

Each time a station runs, the Orchestrator creates a **work record**. It tracks the run's status (`pending`, `running`, `completed`, `failed`), each step's output, and any report and documents the steps attach. You see work records in the Orchestrator and with `fob-orc work-records`.

Within one run, every step can read the outputs of the steps before it.

## Workpieces and bins

A **workpiece** is a folder on the worker's disk holding one unit of work: one invoice, one statement, one email. It carries:

- `pointer.json`: what this workpiece is (an id and where it came from). A folder is a workpiece because it has this file.
- `log.jsonl`: one line per event, such as `station_started` or `station_failed`, with the station and the work record.
- Whatever files the stations add as it moves along.

Each station has five **bins**, folders under `temp/stations/<STATION>/`:

| Bin | Holds |
| --- | --- |
| `input` | Workpieces waiting for this station |
| `doing` | The workpiece being processed right now |
| `output` | Workpieces this station finished; the next station pulls from here |
| `failed` | Workpieces that failed here, with `error.json` and `error.txt` |
| `done` | The untouched input copy of each finished workpiece, kept as a receipt |

The first station on a line (the **line head**) creates workpieces straight into its `output`. Each later station starts with lib-worker's `move_files` step, which moves workpieces from the previous station's `output` into its own `input`.

The Orchestrator never sees the workpieces; it only records each run. See [Workpieces and bins](/docs/workers/workpieces).

## Example

An invoice line with two stations:

```text
IN0  seed invoices    →  output/INV-1001/ … creates one workpiece per invoice
IN1  check invoices   ←  moves IN0/output → IN1/input, then checks each one
                         under the limit → IN1/output    above it → IN1/failed
```

`fob-worker lines status IN` then shows where everything is:

```text
STATION  INPUT  DOING  OUTPUT  FAILED  (DONE)
---------------------------------------------
IN0      —      —      0       —       —
IN1      0      0      2       1       (2)
live     0      0      2       1       —
```