Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

State machines: states, events and guards

UML state modelling, and how it differs from the flowchart you might reach for instead.

Three flags, eight combinations

Open the subscriptions table of a typical SaaS and you may find three columns like is_active, is_past_due and is_paused. Three booleans give eight combinations, and only a few of them mean anything. A row with is_active = false, is_past_due = true and is_paused = true is a real support ticket: is this customer paused, behind on payment, or both? Every piece of code that reads the row answers that question for itself, and not always the same way.

A state machine replaces the flags with one answer. The subscription is in one named state at a time, chosen from a short list, and it moves from one state to another when an event arrives: trialEnded, paymentFailed, retrySucceeded. The diagram lists both the states and the events, so a combination nobody designed has nowhere to be drawn.

Is it doing something, or is it something?

In a flowchart, a box is something the system does. In a state machine, a box is something the system is, and it stays that way until an event moves it. "Validating payment" is a step; "Past due" is a state, and a subscription can sit in it for days while retries succeed or run out. Getting that distinction right is most of the work.

A quick test: if a box always leads to exactly one next box with no event in between, it is usually a step, and it belongs in a flow diagram. State machines as flows shows how to draw a lifecycle with flowchart nodes when that is the better fit. And if the question is who calls whom during one checkout, that is Sequence diagrams: who calls whom, in what order.

A subscription, in the states it can actually be in

Every transition out of a state carries the event that causes it. An unlabelled arrow is a question, not an answer.

Reading an arrow

A transition is written event [guard] / action. The event triggers it, the guard is a condition that must be true for it to fire, and the action runs as it fires. trialEnded / charge needs no guard: when the trial ends, the machine charges the customer and moves to Active. The diagram assumes that first charge succeeds; a real one also needs an arrow for when it does not.

Guards earn their place when one event should lead different ways. Look at retriesExhausted on the diagram: it quietly assumes something else is counting retries. To make the count part of the design, send a single retryFailed / attempts++ into a Choice pseudostate with two guarded exits, [attempts < 3] back into Past due and [else] to the end, with attempts set to 0 by paymentFailed when the subscription first falls into Past due. The Choice is for exactly this case, one event that branches on a condition, and it keeps the guards visible instead of hiding them on parallel arrows out of Past due.

Notice what happens when a failed retry loops back into Past due: the state's entry / scheduleRetry() runs again, and the next retry is booked without anyone writing that call on the new arrow.

Noteentry / and exit / actions belong to the state, not the transition. Put an action there when it must run no matter how the state was entered (or, for exit /, left) — that is how you stop duplicating the same call on five incoming arrows.

An event that arrives twice

Payment providers can deliver the same webhook more than once. Suppose paymentFailed arrives twice for one invoice. The first moves the subscription from Active to Past due. The second finds it already in Past due, which has no paymentFailed transition, and in UML an event that triggers no transition in the current state is discarded, unless that state explicitly defers it. No second retry gets scheduled; the diagram handled the duplicate on its own.

That protection has an edge. If the retry succeeds in between and the duplicate arrives once the subscription is back in Active, paymentFailed is a valid event there, and it moves a paying customer back to Past due. A state machine rejects events that make no sense right now; it cannot tell a late duplicate from a new failure. That takes an event ID, and Idempotency & exactly-once illusions covers how to use one.

Pause, then resume where you were

Then product asks for pause. A customer can pause from Active or from Past due, and on resume should land back in whichever one they left. Drawn flat, that needs a separate Paused state for each, or a flag to remember which one, and a flag is how this started.

A Composite State groups substates that share transitions. Put Active and Past due inside a composite called Paying, and one pause arrow out of Paying applies to both. A History pseudostate remembers which substate you were in, so resume into Paying's History lands where you left off rather than at the start. Landing back in Past due runs its entry / scheduleRetry() again, so give it an exit / cancelRetry(), or a retry booked before the pause fires alongside the new one.

NoteOn a Challenge Grid a Composite State cannot hold its substates inside it, and a state has no compartment for entry / actions. Name each substate with its composite — Paying::Active — name the History pseudostate the same way — Paying::H — and write event [guard] / action in each transition's label.

A diagram like this is a model, not an implementation. When it becomes code, one common shape is a class per state that the owning object delegates to, which is the State pattern.

Where these diagrams usually go wrong

  • Unlabelled transitions out of an ordinary state, when an event is what really moves it. (The arrow from the Initial pseudostate never has a trigger, and a triggerless arrow out of a state means 'as soon as its work completes' — use that on purpose, not by omission.)
  • No final state, or no way to reach it. Every machine that can end should show how; a subscription that runs out of retries has to end somewhere the reader can see.
  • Forgetting the error states. "Suspended", "Failed" and "Expired" are where much of the business logic lives, and they are the states support tickets ask about.

Fix the card while it is paused

Open Subscription States and model pause with a composite state plus a History pseudostate, named the Challenge way: Paying::Active, Paying::PastDue, Paying::H. Then ask what happens if the card is fixed while paused. If the diagram cannot answer, a state, a transition or a guard is missing. For a machine where a Choice does most of the work, Elevator States asks where the car goes next depending on its request queue.

Practice this