What Is a State Machine? States, Events, and Workflow Rules

Key takeaways

• A state machine defines modes of behavior and the events that can move between them.
• Guards determine whether a transition is permitted, while actions describe associated work.
• State modeling exposes invalid transitions but does not automatically solve persistence or concurrency.
• Independent lifecycles may need separate or parallel states instead of one growing list of combinations.

A state machine models behavior using states and allowed transitions. An event is interpreted according to the current state, and it may trigger a transition.

Imagine a document-review system. A document begins as a draft, can be submitted for review, and may then be approved or returned for changes. Only an approved document may be published.

A collection of flags such as isDraft, isApproved, and isPublished can permit contradictory combinations. An explicit lifecycle gives those rules one place to live.

Start With States That Change Behavior

For this workflow, the states are:

• Draft: the author can edit and submit.
• In review: a reviewer can approve or request changes.
• Approved: the document is eligible for publication.
• Published: the approved version is publicly available.

These names matter because they change the allowed operations.

Keep supporting data separate. The document title, reviewer ID, and revision number are relevant context, but they do not each need to become a named state.

The transition model described by Stately relates events and the active state to the next behavior.

Write the Transition Table

Current state	Event	Next state
Draft	Submit	In review
In review	Approve	Approved
In review	Request changes	Draft
Approved	Publish	Published
Approved	Edit	Draft

The last row makes an important policy explicit: changing approved content removes its approval.

This example treats the published revision as final. A new revision would begin its own draft lifecycle. Another product might model unpublishing or archiving, but those transitions should be deliberate additions.

A transition table is already useful before selecting a library or drawing a diagram.

Decide What Invalid Events Mean

What should happen if someone tries to publish a draft?

The machine should not silently jump to published. The application can reject the operation with a useful error, ignore it in a particular UI context, or record it for investigation.

The choice depends on the interface. An API caller may need a conflict response, while a disabled button may prevent the request locally. The server still needs enforcement because the interface can be bypassed.

A schema can restrict the possible status strings. The transition model adds rules about how those strings may change over time.

Guards Add Conditions

Being in review is necessary for approval, but it may not be sufficient.

The reviewer may need permission, required fields may need completion, and the approval may need to refer to the current revision.

A guard expresses a condition required for a transition. Stately’s guard documentation describes guards as conditions evaluated when selecting transitions.

Keep these decisions inspectable. A guard that makes an unpredictable network call can make the transition difficult to reason about. Gather needed information through a defined process, then decide using the relevant state and data.

Actions Describe Work Around a Transition

Approving a document might update stored state and arrange a notification to its author.

The state decision and notification delivery are different responsibilities. If email delivery fails, the system needs an explicit answer about whether approval remains valid and whether the notification will be retried.

Do not assume a transition library makes database writes and external messages one atomic operation.

For a durable workflow, persistence, an outbox or equivalent delivery mechanism, and idempotent processing may be needed. The orchestrator-pattern guide explores coordination across such steps.

Two Events Can Race

Suppose an author edits the approved document just as a publisher requests publication.

Both operations may read the same initial state. Without a concurrency check, one might publish content different from the content that was approved.

A transaction or conditional update using a revision number can ensure the transition applies only to the version that was checked. The losing operation must reread the state and respond appropriately.

Similarly, duplicate approval events should have a defined outcome. An explicit state model helps explain the rule, but the storage layer must enforce it.

Avoid Combining Unrelated Lifecycles

A document might be published while its search indexing is still pending. Those facts need not be mutually exclusive.

Making states such as “published-and-indexing” and “published-and-indexed” can lead to a growing list of combinations.

Separate models or statecharts with parallel states can represent independent concerns. Hierarchical states can organize related substates when the behavior warrants them.

A simple workflow may need only a transition function and a table. Tooling becomes useful when hierarchy, timers, visualization, or coordinated asynchronous behavior add real complexity.

Review Paths Beyond the Happy Case

Walk through editing after approval, duplicate submission, stale reviewer actions, publication failure, and late notifications.

Record the previous state, event, revision, and resulting state so operators can explain what happened. Correlation identifiers help when one action crosses multiple components.

For the review system, success means the published revision is the one that received valid approval. The state machine makes that requirement explicit, while persistence and concurrency controls make it hold in the running application.

Naming a status is useful; defining how that status may change is what makes the model a state machine.