← All posts

The state graph

Status fields work fine until the workflow has consequences. Then every service ends up with its own version of the same thing, and the mechanics of what happens during a transition become bespoke every time.

What we built

Any object in Dawnshard can participate in a state graph. The graph defines the states an object can be in and the transitions between them. An object carries a reference to its graph, its current state, its previous state, and when it entered the current state. The state engine owns all writes to those fields.

A transition connects a source state to a destination state. Some transitions are universal and can fire from any state. One transition per graph is the entry transition, reserved for placing a newly created object into its initial state. After that it is unreachable.

Executing a transition runs a defined sequence: conditions checked before anything begins, exit hooks from the current state, the state update itself, then enter hooks for the new state. All of that happens atomically.

The problem it solves

A status field gets you started. It does not give you a consistent place for what happens during a transition.

One developer puts the side effects in the update method. Another creates a custom state machine in a one-off service. A third adds lifecycle logic directly to the route handler. Each approach is defensible in isolation, and together they make the codebase harder to reason about as it grows. When the workflow needs to become more complex, there is no shared shape to extend.

Defining the state mechanics and the graph rules once gives every domain a consistent foundation. The workflow can grow to meet the complexity of the requirement without reinventing the shape for every service it touches.

The challenge

The graph itself is not complicated. It is nodes and edges, manually defined, driven by user events ninety percent of the time. The work was in finding the right balance for hooks.

Hooks need to be able to do real work: send a notification, update a related record, enforce a domain rule. But they also need to respect the same role boundaries the rest of the system maintains, without forcing every hook through redundant layers of authorization checks that the transition has already satisfied.

Getting that right required a clean mechanism for registering hooks and a clear contract for what context they receive. It went through a couple of fast development cycles before landing in a minimal but complete version. The goal was a hook that could do anything it needed to do intentionally, not one that could quietly bypass the boundaries around it.

What makes this different

The state graph is data. The graph definition lives in the database, not in code, which means it can be modified at runtime without a deployment. It is also reusable across domains: any object that opts into state management gets the same engine, the same transition mechanics, and the same hook system.

That separation between the graph definition and the objects that follow it means the lifecycle rules for a domain can be inspected, modified, and extended in one place. There is no equivalent to that with a status enum baked into a model.

What this unlocks

Dawnshard now has a general-purpose mechanism for object lifecycle that any domain can use without rebuilding it. New workflows plug into the same engine, the same hook registration system, and the same consistent transition model.

The next post covers the realtime engine: how state changes and writes propagate to connected clients without polling.

Liked this post? Tap the heart to let us know.

Get early access

Be the first to hear about early access, roadmap updates, and exclusive early adopter pricing.

Join the early access list