State Machine vs Workflow: When to Use Which

State Machine

A state machine restricts your entity to exactly one place at a time. This is simpler and covers most use cases.

Use a state machine when:

• Your entity follows a linear or branching path
• It can only be in one state at a time
• Examples: order status, ticket lifecycle, user onboarding

framework:
    workflows:
        order:
            type: state_machine
            places: [new, processing, shipped, delivered]

Workflow (Petri Net)

A workflow allows your entity to be in multiple places simultaneously. This enables parallel processing paths.

Use a workflow when:

• Your entity needs to be in multiple states at once
• You have parallel approval or review processes
• Examples: content review (checking spelling AND content simultaneously)

framework:
    workflows:
        article:
            type: workflow
            transitions:
                start_review:
                    from: draft
                    to: [checking_content, checking_spelling]
                publish:
                    from: [content_approved, spelling_approved]
                    to: published

Decision Guide

When in doubt, start with state_machine. You can always upgrade to workflow later if you need parallel states.