Escrow looks simple from the outside. A client funds a milestone, the freelancer works, the client approves, the money moves. Four states and three transitions. It is the least forgiving thing we have built, and the reason is that every ambiguity becomes a question about somebody’s money.
Booleans lie under concurrency
The tempting model is a few flags on a record: funded, submitted, approved, paid. It reads well and it fails the first time two things happen at once. A client approving while a freelancer resubmits, on a row with four independent booleans, has sixteen possible combinations and only a handful are legal.
An explicit state column with an enumerated set of transitions makes the illegal combinations unrepresentable. It is more work to write and considerably less work to reason about at two in the morning.
The transition is the thing worth recording
Storing the current state tells you where a milestone is. It does not tell you how it got there, and during a dispute that is the only question anyone asks. We record every transition with its actor, its timestamp and what triggered it, and treat the current state as a projection of that history rather than the source of truth.
Idempotency is not optional when money moves
A network timeout on a release request must not be able to release twice. Every state-changing request carries a key, and a repeat of the same key returns the original outcome rather than performing the action again. This is a small amount of work at build time and an extremely expensive conversation to have afterwards.
Approval is a trigger, not a status
The design decision that removed the most complexity was making approval directly cause release, rather than setting a flag that some later process reads. Every intermediate step between a client approving and a freelancer being paid is a place where money can sit while somebody investigates.
None of this is specific to marketplaces. Any system where a thing moves through stages and the stages have consequences benefits from the same treatment. It is just that when the thing is money, you find out quickly whether you got it right.
