Concepts
IdentityFlow separates two things that are usually tangled together: the code that describes a process, and the record of what one particular run of it actually did.
If you read only one page before the tutorial, read this one. Everything else assumes these words.
The code. A defineWorkflow call with a name, a version, an input schema, and
an async function containing the logic.
Once a version is deployed it doesn’t change. If you need different behaviour, you publish a new version — runs that are already in flight keep executing the code they started with, which is the only way a run that waits three weeks can mean anything.
One run of one definition. It has its own event stream and it moves through states: active, sleeping, pending, requesting, relying, completed, errored.
“Pending” is the one you’ll see most in the tutorial — it means the run is parked at a dialog, waiting for a person.
An event is an immutable record that something happened. Events are the truth; they are appended and never modified.
A projection is a queryable view built from those events — “which approvals is Alex waiting on?” You can throw a projection away and rebuild it, because the events it came from are still there. That relationship only holds if replay is deterministic, which is why replaying a workflow must never call an external system.
A step is a named unit of work. There are four: do runs code, sleep
waits for a duration, dialog waits for a person, and start launches a child
workflow. The name matters — it’s how a resumed run recognises work it already
finished, so it has to be stable.
A binding is how a workflow reaches anything outside itself. You declare it
with defineBinding(name, factory) and pull it in with flow.use(). In a test
you swap the real implementation for a fake one; the workflow code doesn’t
change.
Keep network and database calls behind bindings, inside a step. If the step can be retried, the system on the far end has to tolerate receiving the same request twice.
Next: Authoring Workflows for the rules you have to follow when writing one.