# 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, checked against its zod schemas. Its **slug** (such as `IN1_01_check`) is how stations refer to it.

## 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 runs on a cron schedule or when you trigger it. You keep stations as JSON files in `.orchestrator/stations/` and push them with fob-orc.

## 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. 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 a `pointer.json` (what it is), a `log.jsonl` (one line per event, such as `station_started` or `station_failed`), and 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.

## 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
```

Full reference: [finopsbricks.com/docs/workers/concepts](https://finopsbricks.com/docs/workers/concepts).