Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

State machines as flows

Draw a lifecycle so that each box names where the entity is and each edge is a legal move, give every state that can fail or be cancelled its own way out, and know what the drawing cannot enforce.

"Where is my application?"

A city's permit office hears that question all day, and a clerk can answer it in a word or two: Submitted, Under review, More documents needed, Approved, Issued, Rejected, Withdrawn. A building-permit application is in exactly one of those at any moment, and it moves between them only in certain ways. A fixed list of states and a fixed set of allowed moves is a finite-state machine, and a flowchart can draw one, as long as you read its boxes differently.

A box says where it is, not what someone does

The first draft usually comes from the clerk's job: Check documents → Inspect plans → Decide → Print permit. As a description of the work that is fine, and on the phone it is useless. An application that has waited three weeks for a missing survey is not in Check documents, because nobody is checking anything. So each box here has to pass one test: can you finish the sentence "the application is…" with it? "Under review" passes; "Check documents" does not. A step is something someone does and finishes; a state is somewhere the application can sit for months with nobody touching it.

The flowchart has no symbol of its own for this, so the shapes get borrowed. A Process box holds the name of a state, an edge is a legal move, a Decision asks which state comes next as the application leaves this one, and an End is a terminal state, one that no edge leaves. Decisions are not states: nobody's application "is Complete?". How a Decision works is in Decisions & branching.

A building-permit application, state by state

What the drawing adds over a list of seven names is the moves. Can a Rejected application come back to life? No edge leaves that End, so in this office it cannot; the applicant files a new one. Can a permit be issued without the fee? Issued has one way in, through Approved and Fee paid?. That is how a required state stays required: the transition that would skip it is simply not drawn.

The way back, and the other ways out

More documents needed is what stops this being a straight line. When the survey arrives the application goes back to Under review, which on the Grid accepts only one incoming edge, so the way back and the first entry both go through a Merge in front of it; Loops & retries explains that shape. Unlike a retry, nothing comes back by itself; a person has to act.

It still needs an exit. Draw only the way back and, a few years on, the office has files listed as More documents needed from applicants who sold the plot and moved away. Lapsed? is that exit: in this office, an application whose applicant drops it, or whose deadline passes with no documents, is treated as withdrawn. The diagram shows those outcomes but not the wait itself; naming what triggers each move, and the condition it depends on, is what UML state diagrams are for: State machines: states, events and guards.

Ask the same of every box: what else, besides the good outcome, can happen to an application sitting here? In Under review the applicant can change their mind, which is Still wanted?. In Approved they can simply never pay; issuing needs the fee, so with only Approved → Issued drawn that applicant has no other move and the application stays Approved for ever, until someone edits the record by hand. The no of Fee paid? is that other move: here, a fee deadline that passes counts as withdrawn. That is also why Approved gets a box: a lifecycle isn't a single branch, it's a sequence of them. The extra branch belongs only where the failure is real. Submitted has one exit on purpose, because a clerk opens each file within days and a withdrawal letter that arrives first is read at Still wanted?.

What the drawing cannot stop

A diagram is a claim about which moves are legal, and it enforces none of them. Someone runs UPDATE applications SET status = 'Issued' on a file still Under review. Nothing in the diagram objects, and unless the system checks the move, the database accepts it and a permit exists that the lifecycle says cannot. Making that jump fail takes code: one place that knows the allowed moves and refuses the others, and that every status change has to go through. For that UPDATE it has to sit in the database, or direct writes have to be shut off.

NoteThis is a finite-state machine drawn as a flow; the State design pattern is one way to implement it in code — see the Design Patterns article on State.

From permits to orders

Open the Order Lifecycle Flow challenge and focus on one thing: giving every state that can actually be cancelled or fail its own path to a cancelled/failed terminal, so that no such state is left with only a happy path. Then read each Process box after "the order is…": one that does not fit is naming work, not a state.

Practice this