UML State Machine Diagrams

A state machine diagram shows the states one object can be in, the events that move it between states, and the conditions on those moves. Developers, testers and product owners read it whenever something has a lifecycle: an order, a ticket, a connection, a model deployment.

1. What a State Machine Diagram Shows

Many bugs come from an object doing something in the wrong state: shipping an unpaid order, refunding twice, retrying a call against a dead service. A state machine makes the allowed states explicit and lists every legal transition. Anything not drawn is forbidden.

UML state machines descend from David Harel's statecharts (1987), which added nesting and concurrency to classic finite-state machines so that real systems stay readable. The same model is used by libraries such as XState (JavaScript), the Python transitions package, and AWS Step Functions-style workflows.

2. Notation

A filled dot is the initial pseudostate; a bullseye is the final state. States are rounded rectangles. A transition arrow is labelled event [guard] / effect: when the event arrives and the guard is true, the effect runs and the object moves. All three parts are optional. A composite state contains its own sub-machine; a transition leaving the composite boundary applies to every substate inside. States may declare entry, do and exit activities. A diamond is a choice point.

3. Example 1: Online Shop Order Lifecycle

Walkthrough: an order starts in Created, moves to AwaitingPayment on submit, and either enters the Fulfilment composite state on paymentOk or is cancelled after a 30-minute timeout. Inside Fulfilment it goes Paid → Shipped → Delivered. The highlighted rule is the guarded transition cancel [not shipped] / refund(): cancelling is only possible from Paid, and it triggers a refund. Each arrow becomes a test case, and each missing arrow becomes a negative test.

4. Example 2: A Circuit Breaker

Walkthrough: a client calling an LLM API wraps calls in a circuit breaker. In Closed, calls pass and failures are counted (a self-transition). The fifth failure trips it to Open, where calls fail immediately. After 30 seconds it moves to HalfOpen and allows one trial call: success resets to Closed, failure goes back to Open. Three states and five transitions capture the whole pattern precisely.

5. Pros, Cons, and When to Use

Pros

• Makes illegal states and transitions impossible to overlook.
• Translates directly into code, enums and transition tables.
• Every arrow is a test case; coverage is easy to measure.
• Composite states keep large lifecycles readable.
• Understood by business stakeholders (order and ticket statuses).
• Supported by executable libraries and workflow engines.

Cons

• Describes one object only; interactions between objects need other diagrams.
• Concurrent regions and history states are hard for beginners.
• Becomes cluttered when every error path is drawn.
• Guards in free text can hide complex logic.
• Easy to let code and diagram drift unless the code is generated from the model.

When to use

• Anything with a status field and rules about how it changes.
• Protocols, connections, retries and UI flows.
• Embedded and device control logic.

When not to use

• Stateless request handlers.
• Process flows involving many actors (use an activity diagram).

6. Reading Tips and Common Mistakes

For each state, ask two questions: which events can arrive here, and what should happen for each? Any event without an arrow is either ignored or a bug; decide which and document it. Then check that every state can reach a final state, otherwise objects can get stuck forever.

Common mistakes: naming states after actions ("Ship") instead of conditions ("Shipped"); turning the diagram into a flowchart where states are really steps; and burying business rules in long guard expressions. Keep guards short and name them after the rule ([withinReturnWindow]).

7. As Diagrams-as-Code

Mermaid's stateDiagram-v2 renders natively in GitHub, GitLab and many docs tools:

stateDiagram-v2
    [*] --> Created
    Created --> AwaitingPayment : submit
    AwaitingPayment --> Fulfilment : paymentOk
    AwaitingPayment --> Cancelled : timeout [after 30 min]
    state Fulfilment {
        [*] --> Paid
        Paid --> Shipped : dispatch
        Shipped --> Delivered : signed
    }
    Paid --> Cancelled : cancel [not shipped] / refund()
    Delivered --> [*]
    Cancelled --> [*]

PlantUML uses nearly identical syntax inside @startuml ... @enduml.

8. Related Diagrams

• UML Diagrams — overview of all 14 UML diagram types and when to use each
• Timing Diagrams — shows the same states laid out against a time axis
• Interaction Overview Diagrams — flow between interactions rather than states
• Object Diagrams — a snapshot of one state in the lifecycle