Pattern
State Machine Design Pattern
Model state transitions explicitly as a finite state machine, making allowed state changes clear, testable, and auditable. This pattern prevents invalid transitions and provides a clear model for how collaborative state evolves over time.
Part 1: The State Machine Design Pattern
Overview
The State Machine Design Pattern treats state transitions as first-class citizens. Instead of allowing arbitrary status updates, you define a finite set of states and the legal transitions between them. Each transition has explicit conditions, triggers, and outcomes.
When multiple people interact with the same state, explicit state machines prevent race conditions, make business rules clear, and enable deterministic behavior even under concurrent access.
When to use this pattern
Use the State Machine Design Pattern when you have:
- Workflow-driven state: Cases, tickets, documents, or orders that move through defined stages
- Business rules: Certain state changes should never happen, or should only happen under specific conditions
- Audit requirements: You need to track and explain how state arrived at its current value
- Concurrent access: Multiple people can trigger state changes, and you need to prevent invalid transitions
- Role-based transitions: Different actors can only trigger certain transitions in certain states
This pattern is less useful for free-form editing (like collaborative text documents) or when state changes are always additive and commutative.
Core concepts
States
A finite set of distinct states that your collaborative object can be in. Examples: Draft, Under Review, Approved, Rejected, Closed.
Transitions
Legal moves from one state to another. Each transition has:
- A source state (where you start)
- A target state (where you end up)
- Conditions that must be true (guards)
- Who can trigger it (action-control policies)
- Side effects or data updates that occur
Actions
User-facing operations that trigger transitions. An action like Submit for Review might trigger the transition from Draft to Under Review.
Events
Records of transitions that actually occurred. Events capture what happened, when, and by whom, forming an audit trail and enabling projections.
Example: Document approval workflow
Consider a document that needs approval:
States:
Draft- Initial state, author can editSubmitted- Waiting for reviewUnder Review- Reviewer is examiningApproved- Final state, document is acceptedRejected- Final state, needs revisionRevising- Author is making changes after rejection
Transitions:
Draft → Submitted(by author)Submitted → Under Review(by reviewer)Under Review → Approved(by reviewer)Under Review → Rejected(by reviewer)Rejected → Revising(by author)Revising → Submitted(by author)
Notice that Draft → Approved is not a legal transition. The state machine enforces that documents must go through review. This prevents shortcuts and ensures process compliance.
Benefits
- Prevents invalid states: The machine rejects transitions that shouldn't happen, catching bugs early
- Clear business rules: Allowed transitions document your process explicitly
- Testable: You can test all legal transitions and verify invalid ones are rejected
- Auditable: Event history shows exactly how state evolved
- Concurrent-safe: Transition validation prevents race conditions
- Self-documenting: The state machine itself serves as documentation
Part 2: State Machines in the State-Based Collaboration Framework
How state machines fit in the framework
The State Machine Design Pattern is fundamental to the State-Based Collaboration Framework's Transitions component. The framework uses state machines to provide structure where ad-hoc status fields would otherwise lead to inconsistent behavior and hard-to-reason-about edge cases.
In the framework, state machines are defined explicitly with:
- A finite set of states that collaborative objects can be in
- Explicit transitions that define legal state changes
- Actions that trigger transitions (mapped to the Framework's Actions component)
- Action-control policies that determine who can trigger which transitions in which states
- Guard conditions that must be true before transitions can occur
- Events that record transitions as they occur (mapped to the Framework's Events component)
Framework components and state machines
State machines in the framework integrate with several components:
States component
The framework's States component defines the state space—the set of all possible states that collaborative objects can be in. This becomes the state machine's state set.
Transitions component
The Transitions component implements the state machine itself, defining which transitions are legal and under what conditions. Each transition maps from a source state to a target state.
Actions component
Actions are user-facing operations that trigger state machine transitions. The framework maps actions to transitions, making it clear which actions are available in which states.
Action-Control Policies
These policies determine who can trigger which transitions in which states. They encode role-based and permission-based rules that govern the state machine's behavior.
Events component
Every state machine transition generates an event, recording what happened, when, and by whom. This creates an audit trail and enables projections.
Related patterns
This pattern works well with:
- Framework overview - Learn about transitions and action-control policies
Explore more patterns
This pattern is one of many for building collaborative systems. Check out other patterns or dive deeper into the framework components.