State Machine Diagram

What this diagram shows

A state machine diagram illustrates how an entity progresses through a finite set of discrete states based on triggering events or conditions. It maps all possible states an object can occupy and the transitions between them, each triggered by specific events, guards, or actions. The diagram shows the flow from an initial state through intermediate states to one or more final states, making explicit the legal pathways and impossible transitions. This representation clarifies behaviour that would be difficult to express in prose or pseudocode, especially when multiple conditions govern state changes.

Key components

• Initial State — The starting point where the entity begins, represented as a filled circle with an arrow pointing to the first active state.
• State — A named condition or mode the entity occupies, drawn as a rounded rectangle, where the system remains until an event triggers a transition.
• Transition — A directed arrow connecting two states, labelled with the event, guard condition, and optional action that causes the state change.
• Event — A trigger such as a user action, signal, or message that initiates a potential state transition when conditions allow.
• Guard Condition — A boolean expression enclosed in square brackets that must evaluate to true for a transition to fire, even if its event occurs.
• Action — An optional operation executed during a transition, written after a forward slash on the transition label to represent side effects.
• Final State — An end state represented as a filled circle inside a larger circle, indicating termination or completion of the state machine's execution.

When to use it

Use a state machine diagram when you need to specify behaviour that depends on the current state and cannot be expressed with simple sequential flow. It is essential for modelling workflow states (draft, submitted, approved, published), device operation modes (idle, processing, error), game entities with distinct behaviours, authentication flows, or any system where illegal state transitions must be prevented. This diagram becomes particularly valuable when documenting complex user interactions or protocol requirements where the order and conditions of state changes are critical to correctness.

Common mistakes

• Omitting guard conditions or showing all transitions as equally valid, which masks the actual constraints and makes the diagram less useful for implementation or validation.
• Creating states at inconsistent levels of abstraction, mixing high-level phases (payment processing) with low-level technical states (network retry), which obscures the real control logic.
• Forgetting to mark the initial and final states explicitly, forcing readers to infer entry and exit points instead of making the state machine's scope unambiguous.

Adapting it to your system

Replace the generic state names with the actual states relevant to your domain: for order processing, use states like pending, payment authorized, packed, shipped, delivered. Name events after real triggers: submit order, payment received, inventory depleted. Specify guard conditions based on actual business rules, such as [quantity in stock] or [user has admin role]. Add actions that reflect what your system must do, such as send email notification or update database. Ensure transitions cover all realistic pathways but explicitly exclude impossible or forbidden transitions to make the diagram a true specification of legal behaviour.