state-machine-design

State Machine Design Skill When to Use This Skill

Use this skill when:

State Machine Design tasks - Working on statechart and state machine modeling for lifecycle and behavior specification Planning or design - Need guidance on State Machine Design approaches Best practices - Want to follow established patterns and standards Overview

Design finite state machines and statecharts for modeling entity lifecycles, workflows, and system behavior.

MANDATORY: Documentation-First Approach

Before designing state machines:

Invoke docs-management skill for state machine patterns Verify implementation patterns via MCP servers (context7 for XState, etc.) Base all guidance on Harel statechart semantics State Machine Concepts Core Elements Element Description Example State Condition the system can be in Draft, Submitted, Paid Transition Change from one state to another Draft → Submitted Event Trigger for a transition Submit, Pay, Cancel Guard Condition that must be true [hasItems], [isValid] Action Side effect on transition sendNotification, updateDatabase Entry Action Action when entering state onEnter: startTimer Exit Action Action when leaving state onExit: stopTimer State Types public enum StateType { Initial, // Starting state (filled circle) Normal, // Regular state Final, // End state (circle with border) Composite, // Contains sub-states Parallel, // Concurrent regions History, // Remember last sub-state Choice // Decision point }

State Machine Notation PlantUML Syntax @startuml title Order State Machine

[*] --> Draft : Create

state Draft { Draft : entry / initializeOrder Draft : exit / validateOrder }

Draft --> Submitted : Submit [hasItems] Draft --> Cancelled : Cancel

state Submitted { Submitted : entry / reserveInventory }

Submitted --> Paid : ProcessPayment [paymentValid] Submitted --> Cancelled : Cancel / releaseInventory Submitted --> Draft : RequireChanges

state Paid { Paid : entry / confirmInventory }

Paid --> Shipped : Ship Paid --> Refunded : Refund

state Shipped { Shipped : entry / sendTrackingNotification }

Shipped --> Delivered : Deliver Shipped --> Returned : Return

Delivered --> Completed : Finalize Delivered --> Returned : Return

Returned --> Refunded : ProcessReturn

Completed --> [] Refunded --> [] Cancelled --> [*]

@enduml

Mermaid Syntax stateDiagram-v2 [*] --> Draft : Create

state Draft {
    direction LR
    [*] --> Empty
    Empty --> HasItems : AddItem
    HasItems --> HasItems : AddItem
    HasItems --> Empty : RemoveLastItem
}

Draft --> Submitted : Submit
Draft --> Cancelled : Cancel

Submitted --> Paid : PaymentReceived
Submitted --> Cancelled : Cancel
Submitted --> Draft : RequireChanges

Paid --> Shipped : Ship
Paid --> Refunded : Refund

Shipped --> Delivered : Deliver
Shipped --> Returned : Return

Delivered --> Completed : Finalize
Delivered --> Returned : Return

Returned --> Refunded : ProcessReturn

Completed --> [*]
Refunded --> [*]
Cancelled --> [*]

C# Implementation Patterns Simple State Machine public sealed class Order : Entity { public OrderStatus Status { get; private set; }

private static readonly Dictionary<(OrderStatus From, OrderEvent Event), OrderStatus> _transitions =
    new()
    {
        { (OrderStatus.Draft, OrderEvent.Submit), OrderStatus.Submitted },
        { (OrderStatus.Draft, OrderEvent.Cancel), OrderStatus.Cancelled },
        { (OrderStatus.Submitted, OrderEvent.Pay), OrderStatus.Paid },
        { (OrderStatus.Submitted, OrderEvent.Cancel), OrderStatus.Cancelled },
        { (OrderStatus.Submitted, OrderEvent.RequireChanges), OrderStatus.Draft },
        { (OrderStatus.Paid, OrderEvent.Ship), OrderStatus.Shipped },
        { (OrderStatus.Paid, OrderEvent.Refund), OrderStatus.Refunded },
        { (OrderStatus.Shipped, OrderEvent.Deliver), OrderStatus.Delivered },
        { (OrderStatus.Shipped, OrderEvent.Return), OrderStatus.Returned },
        { (OrderStatus.Delivered, OrderEvent.Finalize), OrderStatus.Completed },
        { (OrderStatus.Delivered, OrderEvent.Return), OrderStatus.Returned },
        { (OrderStatus.Returned, OrderEvent.ProcessReturn), OrderStatus.Refunded },
    };

public Result Transition(OrderEvent @event)
{
    if (!_transitions.TryGetValue((Status, @event), out var newStatus))
    {
        return Result.Failure($"Cannot {@event} order in {Status} status");
    }

    var oldStatus = Status;
    Status = newStatus;

    AddDomainEvent(new OrderStatusChangedEvent(Id, oldStatus, newStatus, @event));

    return Result.Success();
}

}

public enum OrderStatus { Draft, Submitted, Paid, Shipped, Delivered, Completed, Cancelled, Returned, Refunded }

public enum OrderEvent { Submit, Cancel, Pay, RequireChanges, Ship, Refund, Deliver, Return, Finalize, ProcessReturn }

State Pattern Implementation public abstract class OrderState { public abstract OrderStatus Status { get; }

public virtual Result Submit(Order order) =>
    Result.Failure($"Cannot submit order in {Status} state");

public virtual Result Cancel(Order order) =>
    Result.Failure($"Cannot cancel order in {Status} state");

public virtual Result Pay(Order order) =>
    Result.Failure($"Cannot pay order in {Status} state");

public virtual Result Ship(Order order) =>
    Result.Failure($"Cannot ship order in {Status} state");

protected void TransitionTo(Order order, OrderState newState)
{
    order.SetState(newState);
}

}

public sealed class DraftState : OrderState { public override OrderStatus Status => OrderStatus.Draft;

public override Result Submit(Order order)
{
    if (!order.HasItems)
        return Result.Failure("Order must have items to submit");

    TransitionTo(order, new SubmittedState());
    order.ReserveInventory();
    return Result.Success();
}

public override Result Cancel(Order order)
{
    TransitionTo(order, new CancelledState());
    return Result.Success();
}

}

public sealed class SubmittedState : OrderState { public override OrderStatus Status => OrderStatus.Submitted;

public override Result Pay(Order order)
{
    TransitionTo(order, new PaidState());
    order.ConfirmInventory();
    return Result.Success();
}

public override Result Cancel(Order order)
{
    order.ReleaseInventory();
    TransitionTo(order, new CancelledState());
    return Result.Success();
}

}

Stateless Library Pattern using Stateless;

public sealed class OrderStateMachine { private readonly StateMachine _machine; private readonly Order _order;

public OrderStateMachine(Order order)
{
    _order = order;
    _machine = new StateMachine<OrderStatus, OrderEvent>(
        () => order.Status,
        status => order.SetStatus(status));

    ConfigureTransitions();
}

private void ConfigureTransitions()
{
    _machine.Configure(OrderStatus.Draft)
        .Permit(OrderEvent.Submit, OrderStatus.Submitted)
        .Permit(OrderEvent.Cancel, OrderStatus.Cancelled)
        .OnEntry(() => _order.InitializeOrder());

    _machine.Configure(OrderStatus.Submitted)
        .PermitIf(OrderEvent.Pay, OrderStatus.Paid,
            () => _order.PaymentIsValid)
        .Permit(OrderEvent.Cancel, OrderStatus.Cancelled)
        .Permit(OrderEvent.RequireChanges, OrderStatus.Draft)
        .OnEntry(() => _order.ReserveInventory())
        .OnExit(() => { /* cleanup if needed */ });

    _machine.Configure(OrderStatus.Paid)
        .Permit(OrderEvent.Ship, OrderStatus.Shipped)
        .Permit(OrderEvent.Refund, OrderStatus.Refunded)
        .OnEntry(() => _order.ConfirmInventory());

    _machine.Configure(OrderStatus.Shipped)
        .Permit(OrderEvent.Deliver, OrderStatus.Delivered)
        .Permit(OrderEvent.Return, OrderStatus.Returned)
        .OnEntry(() => _order.SendTrackingNotification());

    _machine.Configure(OrderStatus.Delivered)
        .Permit(OrderEvent.Finalize, OrderStatus.Completed)
        .Permit(OrderEvent.Return, OrderStatus.Returned);

    _machine.Configure(OrderStatus.Returned)
        .Permit(OrderEvent.ProcessReturn, OrderStatus.Refunded);

    // Terminal states
    _machine.Configure(OrderStatus.Completed);
    _machine.Configure(OrderStatus.Cancelled);
    _machine.Configure(OrderStatus.Refunded);
}

public bool CanFire(OrderEvent trigger) => _machine.CanFire(trigger);

public void Fire(OrderEvent trigger) => _machine.Fire(trigger);

public IEnumerable<OrderEvent> GetPermittedTriggers() =>
    _machine.GetPermittedTriggers();

}

XState Pattern (TypeScript) import { createMachine, assign } from 'xstate';

interface OrderContext { items: LineItem[]; customerId: string; paymentId?: string; trackingNumber?: string; }

type OrderEvent = | { type: 'ADD_ITEM'; item: LineItem } | { type: 'REMOVE_ITEM'; itemId: string } | { type: 'SUBMIT' } | { type: 'PAY'; paymentId: string } | { type: 'CANCEL' } | { type: 'SHIP'; trackingNumber: string } | { type: 'DELIVER' } | { type: 'RETURN' } | { type: 'REFUND' };

const orderMachine = createMachine({ id: 'order', initial: 'draft', context: { items: [], customerId: '', } as OrderContext,

states: { draft: { entry: 'initializeOrder', on: { ADD_ITEM: { actions: assign({ items: ({ context, event }) => [...context.items, event.item], }), }, REMOVE_ITEM: { actions: assign({ items: ({ context, event }) => context.items.filter(i => i.id !== event.itemId), }), }, SUBMIT: { target: 'submitted', guard: 'hasItems', }, CANCEL: 'cancelled', }, },

submitted: {
  entry: 'reserveInventory',
  exit: 'onSubmittedExit',
  on: {
    PAY: {
      target: 'paid',
      guard: 'paymentValid',
      actions: assign({
        paymentId: ({ event }) => event.paymentId,
      }),
    },
    CANCEL: {
      target: 'cancelled',
      actions: 'releaseInventory',
    },
  },
},

paid: {
  entry: 'confirmInventory',
  on: {
    SHIP: {
      target: 'shipped',
      actions: assign({
        trackingNumber: ({ event }) => event.trackingNumber,
      }),
    },
    REFUND: 'refunded',
  },
},

shipped: {
  entry: 'sendTrackingNotification',
  on: {
    DELIVER: 'delivered',
    RETURN: 'returned',
  },
},

delivered: {
  on: {
    RETURN: 'returned',
  },
  after: {
    // Auto-complete after 14 days
    '14d': 'completed',
  },
},

returned: {
  on: {
    REFUND: 'refunded',
  },
},

completed: { type: 'final' },
cancelled: { type: 'final' },
refunded: { type: 'final' },

}, }, { guards: { hasItems: ({ context }) => context.items.length > 0, paymentValid: ({ event }) => event.type === 'PAY' && !!event.paymentId, }, actions: { initializeOrder: () => console.log('Order initialized'), reserveInventory: ({ context }) => console.log(Reserving ${context.items.length} items), confirmInventory: () => console.log('Inventory confirmed'), releaseInventory: () => console.log('Inventory released'), sendTrackingNotification: ({ context }) => console.log(Tracking: ${context.trackingNumber}), }, });

Design Best Practices State Design Guidelines Name states as conditions: Submitted not Submit Name events as commands: Submit not Submitted Use guards for conditional transitions Keep states atomic: One responsibility per state Document entry/exit actions Consider terminal states (final states) Common Patterns Pattern Use Case Linear Simple sequential flow Choice Conditional branching Parallel Concurrent activities Hierarchical Complex nested states History Resume from last state Workflow

When designing state machines:

Identify entity: What has the lifecycle? List states: What conditions can it be in? Define events: What triggers state changes? Map transitions: State + Event → New State Add guards: What conditions must be true? Define actions: What happens on transitions? Draw diagram: Visualize for review Implement: Choose appropriate pattern References

For detailed guidance:

Last Updated: 2025-12-26