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:

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.