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.

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.

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.

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

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

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