State Machine: What It Is, Its Notation, and How to Build One

A state machine describes a thing that is something at any moment — draft, active, suspended, closed — and the events that move it between those conditions. If you have ever argued about whether a cancelled order can be refunded, you were arguing about a state machine that nobody had drawn.

Live interactive diagramUse the player controls to follow the steps

The employee lifecycle, applicant to alumniPlaying silently in this guideWatch with narrationOpen in editor

What a state machine actually is

Formally: a finite set of states, a set of events, and a transition function saying which event moves which state to which other state. Practically: the definitive answer to “what can happen next, and what cannot”.

The formalism goes back to McCulloch and Pitts in 1943 and was refined by David Harel in 1987, whose statecharts added nesting and history to the UML form used today. The reason it survives is that it is exhaustive in a way prose never is: every state × event pair either has a defined transition or is explicitly impossible.

A flowchart shows what happens in order. A state machine shows what is allowed. When a bug report says “it should not have been possible to…”, you needed this diagram.

The parts, and what each one promises

• State — a rounded rectangle. A condition the thing rests in. Name it as an adjective or past participle — Submitted, Active, Expired — never as a verb, which is the giveaway that you have drawn a step instead.
• Transition — an arrow, labelled with the event that causes it. An unlabelled transition is the commonest defect: it implies the change happens by itself.
• Initial pseudostate — the filled circle. Exactly one, and it says what a thing is the moment it exists.
• Final state — the ringed circle. Not every machine has one; a loyalty tier or a subscription may cycle forever, and forcing a terminal state on it is a misrepresentation.
• Guard — a condition in brackets on a transition: [balance > 0]. The event fires only when the guard holds.
• Self-transition — an event that fires without changing state. Worth drawing when it has an effect, like a retry counter.
• Composite state — a state containing its own machine. This is how you keep a large lifecycle readable: collapse a phase and give it its own diagram.

Why draw one at all

• It finds the transitions nobody defined. Enumerate the states, enumerate the events, and the empty cells are decisions your team has not made. Those empty cells become production bugs.
• It settles “can this happen?” permanently. An arrow exists or it does not. No other artefact answers that question so cleanly.
• It maps directly to code and to tests. States become an enum, transitions become the allowed moves, and the diagram is a test matrix you can hand to QA.

When to reach for one — and when not to

• The steps happen in order and mostly do not revisit → a flowchart. See building a clear flowchart.
• You care about who does each part → a swimlane.
• The interesting thing is the exchange between systems → a sequence diagram, and making one people can follow.
• You are tracking work items across columns → a Kanban board. A board is a state machine you can drag, with the transitions left implicit.
• There are only two or three states and no contested transitions → a sentence will do. Not everything needs a diagram.

Who actually draws these

• Backend engineers — order, payment, subscription and document lifecycles, where the states are literally an enum in the database.
• QA and test engineers — the diagram is a coverage matrix; every transition is a test case and every missing one is a gap.
• Product managers — defining what a status means before engineering picks one by accident.
• Security and platform — key, certificate and credential lifecycles, where an illegal transition is a vulnerability.
• Operations and HR — employee, case and asset lifecycles that span systems and teams.
• Teachers — life cycles, phases of matter, and anything cyclical.

Examples you can open and edit

Lifecycles from HR, finance, security and retail, plus several narrated science explainers that show how the notation handles a cycle. Open one and rename the states.

Building one in Diagramium

1. List the states before you draw anything. If two of them are only distinguishable by a sentence of explanation, they are one state.
2. Name them as conditions, not actions. Awaiting approval, not Approve.
3. Add the initial pseudostate and be explicit about what the thing is at creation.
4. Draw every transition you know, and label each with its event. Guards go in brackets.
5. Then do the exhaustive pass. Take each state and ask what every event does to it. Most of the value of this diagram is produced in this step, and it is the step people skip.
6. Record the “impossible” ones in step notes. “Cancelled cannot be refunded — refund happens before cancellation” is worth more than the arrow you did not draw.
7. Press Present. Revealing one state at a time turns a dense graph into a walkthrough, which is how you get a room to actually review it.
8. Export as SVG for the design doc, or hand QA the project file so the test matrix and the diagram cannot drift.

Design decisions that separate a good one from a mess

• Nine states or fewer per diagram. Past that, collapse a phase into a composite state and give it its own machine.
• Lay the happy path along one axis and let the exceptional transitions leave it. A reader should be able to trace the normal life in a straight line.
• Label every arrow. No exceptions — an unlabelled transition is a claim that state changes spontaneously.
• Colour terminal and error states only. They are what people scan for.
• Put the guard on the arrow, the reasoning in the note. Long conditions on a label make the graph unreadable.

Common mistakes

• States named as verbs. Processing payment is a step; Payment pending is a state. Mixing the two produces a flowchart with rounded corners.
• Unlabelled transitions. The reader cannot tell what causes the change, which was the entire question.
• Skipping the exhaustive pass. The undrawn transitions are the bugs; drawing only the ones you already knew adds nothing.
• Forcing a final state onto a cycle. Subscriptions and tiers legitimately never end.
• Twenty states on one canvas. Nobody reviews it, so the errors survive.
• Modelling the UI instead of the entity. Screens are not states; the order is in one state whichever page you are looking at.

The checklist

Run this before you share it.

1. Every state is a condition, named as an adjective or participle.
2. Exactly one initial pseudostate.
3. Every transition carries the event that causes it.
4. Guards are explicit where a transition is conditional.
5. You have walked every state × event pair, not only the ones you knew.
6. Deliberately impossible transitions are recorded in notes.
7. Nine states or fewer, or split into composite states.
8. Terminal states exist only if the thing genuinely ends.