State Machines & Statecharts

What

A state machine: one machine in exactly one state at a time, moving only on declared events. A statechart adds nesting, parallelism, and data. Every machine built with Mantaq is a statechart.

Why

Plain flows use scattered flags (currentStep, booleans) that drift out of sync. A state machine removes that: the situation is the state, the only way to change it is a declared transition triggered by a declared event. No hidden in-between situations exist because they were never defined.

Basics

A state is one known situation. The checkout has basicInfo, payment, success. Always exactly one.

An event is something that happens and can move the machine (submitPayment, back). Only events move the machine.

A transition is a move from one state to another, triggered by an event.

A guard decides whether a transition fires. In Mantaq, the guard lives inside the handler (no separate guard syntax).

One state at a time

The machine is always in exactly one state. Being in payment means not in submitting. This is what makes it different from a bag of flags: flags can disagree, a machine cannot.

• Initial state: where the machine starts (basicInfo).
• Final state: the machine is done and won’t accept anything else (success).

The checkout, drawn as a chart

basicInfo → shippingAddress → payment → submitting → success (final)
                   ↕ (back) ↕                  ↕ (back)
                                            error

Each arrow is a transition. Each box is a state. back moves to an earlier step. From error the machine returns to payment for a retry.

What a statechart adds

• Nesting. A state contains a whole sub-machine. Parent and child each keep their own states.
• Parallelism. Several child flows run at once. Neither blocks the other.
• Extended state. Data alongside the current state. Without it you’d need a separate state for every data combination.

Terms

Term	Meaning
State	One known situation the machine can be in.
Statechart	State machine with nesting, parallelism, and data.
Event	Something that happens and can move the machine.
Transition	A move from one state to another, triggered by an event.
Guard	Condition a transition must pass to fire.
Initial state	Where the machine starts.
Final state	End of the machine; nothing accepted after it.
Extended state	Data the machine carries alongside its current state.
Entry action	Runs when a state is entered.
Exit action	Runs when a state is left; leaving cancels in-flight work.
Compound state	A state containing its own nested flow.
Orthogonal regions	Parallel parts of a machine, running at once.
Determinism	Same state + event + data = same result, always.

For a full glossary, see GLOSSARY.md.