SA-301g · Module 2

State Transition Diagrams

3 min read

State transition diagrams show the states an entity can be in and the transitions between them. An order is "placed," then "paid," then "shipped," then "delivered." But it can also be "cancelled" from "placed" or "paid," and "returned" from "delivered." The state diagram reveals the business rules that govern entity lifecycle — and missing transitions are the bugs that state diagrams catch before they reach production.

Do This

  • Include every valid state and every valid transition — completeness is the value of the diagram
  • Label transitions with the event or action that triggers them — "PaymentReceived" triggers Placed → Paid
  • Mark terminal states explicitly — Delivered, Cancelled, and Refunded are states with no outgoing transitions

Avoid This

  • Show only the happy path — the diagram's value is in the edge cases and the transitions that are not obvious
  • Omit guard conditions — "can only cancel if not yet shipped" is a business rule that belongs on the transition
  • Create state diagrams for entities with two or three states — the diagram adds no value when the lifecycle is trivial