Road to State Machines Part I

Let's begin with a very fundamental question whose answer is not so obvious.

How to design software that always takes the correct action?

Part 1 — Designing Systems When the Past Determines What Is Allowed Next

Let's assume we are developing an e-commerce store and are just implementing the shipping feature.

A single operation that acts on a specific order.

ship_order(order)

What should it do?

That depends on what has already happened:

• If the order has just been created, shipping should be rejected because the customer has not paid.

• Once payment has been captured, the system should create a shipment.

• If the order has already shipped, it should return the existing shipment or reject the duplicate request rather than create another one.

• If the customer has canceled the order, shipping must not happen at all.

The ship_order command remains the same, but its correct interpretation changes over time.

This brings us to a situation where the command alone is therefore insufficient to determine the correct behavior. The system must also know something about what happened before.

That is the basic problem from which state machines emerge.

Start with the smallest model

Suppose we are building a basic order-fulfillment application.

Let's start with the most basic implementation; Our very first model contains only an identifier:

from dataclasses import dataclass


@dataclass
class Order:
    id: str

And we can create an order:

order = Order(id="order-66")

Now the application receives:

ship_order(order)

Can it proceed?

The object cannot answer because it tells us only which order we are discussing. It does not tell us whether the order was paid, canceled, shipped, or delivered.

The smallest useful improvement is to retain the order’s current condition.\
Let's improve our model a bit by adding a status field so that our basic system can distinguish several stages.

@dataclass
class Order:
    id: str
    status: str = "created"

Their intended progression is straightforward:

CREATED → PAID → SHIPPED

We can implement that progression directly:

def capture_payment(order: Order) -> None:
    order.status = "paid"


def ship_order(order: Order) -> None:
    order.status = "shipped"

We never captured payment, yet the order is marked as shipped.

The status field records the order’s current stage. It does not enforce the rules for reaching that stage.

What code does not show?

The model now has two fields. However, they do not do the same work.

• id names the order. Change it, and you are talking about a different order. It does not change what ship_order may do.

• status sits next to it, as if it were the same kind of value. It is not. It bears a role the field does not show. Change created to paid, and the system is allowed to ship. Change it to shipped, and the same command must stop.

That role is invisible in the class.

Both fields are strings, but our business rules give them different responsibilities. The status should influence whether shipping is allowed; our current code does not check it.

Both fields actually store data, but one of them has a different responsibility.

Let's call that role state, for now. That is the role that changes how the system acts next.

Let's improve the model a bit by adding a customer_name field.

@dataclass
class Order:
    id: str
    customer_name: str
    status: str = "created"

Three fields. Two of them still haven't decided what happens next.

Changing the customer_name from Alice to Alice Russel does not necessarily affect whether the order may be shipped. However, changing the status from created to shipped does.

Change status from created to shipped, and shipping does care. That field is still doing the other job. That is still state.

The status changes the set of valid future operations. That makes it a behavioral state.

A useful distinction is:

• Ordinary data: describes the entity

• Behavioral state: changes how the entity may respond

But... Although it is useful, the boundaries of this distinction are not so rigid.

Let me add one more field, delivery_address, to our model to make my point clear.

@dataclass
class Order:
    id: str
    customer_name: str
    delivery_address: str
    status: str = "created"

A delivery address may initially be ordinary data. Once the package has been handed to a carrier, changing that address may become forbidden or require a separate process. The field itself has not changed, but its role in the system’s behavior has.

State is therefore not an intrinsic property of a database column. It is a role information plays in deciding what may happen next.

So the distinction is contextual.

A short name for a longer past

The record says status = "paid". That is where the order is. It is not how the order got there.

One order can be paid by card, while another can be paid by bank transfer.

The paths differ, but both orders are marked as PAID

For shipping, the path may not matter. Paid is enough. The state hides the difference.

Let's call the events we left behind history.

The state summarizes a relevant consequence of the past. It does not preserve everything that happened.

We’ll use history to mean the sequence of events that led to the current situation, whether or not we store that sequence explicitly.

Whether a summary is sufficient depends on the decision we need to make. Consider a future refund operation. A paid label alone would not give us the payment reference or amount needed to issue the refund.

So, improve our system a bit more by adding a Payment class:

from decimal import Decimal
from typing import Optional


@dataclass
class Payment:
    method: str
    provider: str
    payment_id: str
    captured_amount: Decimal


@dataclass
class Order:
    id: str
    customer_name: str
    delivery_address: str
    status: str = "created"
    payment: Optional[Payment] = None

For this example, each order has at most one payment that covers the full amount, and all amounts use the same currency. We use Decimal to represent monetary values.

A paid order might look like this:

payment = Payment(
    method="credit_card",
    provider="stripe",
    payment_id="payment-81",
    captured_amount=Decimal("120.00"),
)

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
    status="paid",
    payment=payment,
)

Now that the model includes payment details, our simulated payment function should store them too:

def capture_payment(order: Order, payment: Payment) -> None:
    order.payment = payment
    order.status = "paid"

We now have three related concepts:

• Lifecycle state helps determine which operations are eligible.

• Supporting data supplies details for those operations and may impose additional conditions.

• History describes the events that produced the current situation.

What the model still allows

We have already shown an invalid change: shipping an unpaid order. Adding more fields leaves two further problems unresolved.

Inconsistent combinations

For this simplified lifecycle, let’s require a captured payment record for every paid or shipped order, and no captured payment record for a created order.

The model does not enforce those rules. It accepts an order marked as paid without a payment record:

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
    status="paid",
    payment=None,
)

It also accepts an order marked as created with the captured payment we constructed earlier:

order = Order(
    id="order-66",
    customer_name="Alice",
    delivery_address="Istanbul",
    status="created",
    payment=payment,
)

These combinations contradict our stated rules. The additional fields give us a richer record, but no checks ensure that their values agree.

Unknown status values

Because status is an unrestricted string, the model also accepts values outside our intended lifecycle:

order.status = "shiped"
order.status = "some_unknown_status"

Python accepts both assignments. Neither value belongs to the vocabulary we intended to use.

The record is our model of reality

There is another boundary to keep in mind. A record marked paid tells us what the application has stored. By itself, it does not prove that a payment provider captured the money.

In a real integration, payment could succeed while the local update fails. Our records could then disagree with the provider.

Those failures belong to later parts of the tutorial. Here, we are examining a simpler problem that already exists with one writer and no external services: the model accepts changes that violate our own rules.

Remembering a condition and enforcing its rules

The status field can tell us where the order claims to be.

It cannot say:

• Which values are valid? (such as "created" or "CREATED")

• Which changes are allowed? (such as changing from "paid" to "shipped" requires a payment)

• Which condition must come first? (such as changing from "created" to "paid" is allowed)

• Which operations must be rejected? (such as changing from "created" to "shipped" must be forbidden)

Let's call this the difference between the memory problem and the correctness problem.

We can now distinguish two problems:

• The memory problem: retain enough information from the past to inform the next decision.

• The correctness problem: enforce the business rules governing valid conditions and changes.

We still need to enforce three kinds of rules:

• Valid values: the status must be created, paid, or shipped.

• Allowed transitions: a simulated successful payment moves an order from created to paid; shipping moves it from paid to shipped. Shipping directly from created must be rejected.

• Consistent data: a paid or shipped order must retain its captured payment record.

A transition is a change from one state to another. Recording the current state does not tell our code which transitions to allow.

Our intended status values give us a vocabulary. Transition rules give us a grammar.

We can name the stages an order may occupy, but our implementation still accepts paths that the business forbids. The rules exist in our explanation; they are not yet enforced by the code.

The next step is to make those rules explicit and enforce them whenever the order changes.

That is where we begin building a state machine.