Building a Prediction Market From Scratch (3): Three Services and the Journey of One Order

The first time I took apart a real trading system, the thing that threw me wasn’t the matching math. It was that the matching engine seemed to be guarded like something precious — kept away from the network, away from the database, fed through a narrow slot. It took me a while to understand why, and once I did, a lot of architectural decisions that had looked arbitrary suddenly made sense.

So before we read any engine code, let me walk you through the shape of this system: why it’s three services instead of one, and what actually happens to a single order from the moment it leaves your terminal to the moment it becomes a trade.

Why three services

You could cram all of this into one process. But splitting it into three, each minding its own business, buys you something real.

There’s the Server — the HTTP API. It faces the network, speaks JSON, checks your token, validates your request. It does no matching whatsoever.

There’s the Engine — matching, the order book, balances, positions. This is the part that has to be fast and certain. It keeps all its state in memory and processes commands one at a time, in order, through a single actor. No locks, no races, no two threads arguing over the same balance.

And there’s the DB Worker — persistence and history. Databases are slow and occasionally moody, so we keep that slowness on the far side of a wall.

The decision underneath all three is one belief I hold strongly: the matching engine must be fast and deterministic, so it isn’t allowed to do anything slow. It can’t block on a network call, can’t wait on a database write. Those slow chores get pushed out to the two ends, and a message queue sits in the middle to decouple them. Everything else about the architecture falls out of that one rule.

The picture

                 ┌────────────┐  server_requests   ┌────────────┐
   HTTP client → │   Server   │ ─────────────────→ │   Engine   │
                 │ (Actix-web)│ ←───────────────── │ (matching) │
                 └─────┬──────┘   reply by id       └─────┬──────┘
                       │ db_read_requests                 │ db_events
                       ▼                                  ▼
                 ┌──────────────────────────────────────────────┐
                 │            DB Worker  (PostgreSQL)             │
                 └──────────────────────────────────────────────┘

The services never call each other directly. They pass messages over Redis Streams — named channels you can append to and read from. The Server drops a request onto a stream; the Engine reads it, works, and replies on another; the Engine also emits events that the DB Worker quietly consumes and writes down.

What happens to one order

Remember the limit bid from the hands-on chapter — Alice buying YES at 60. Here’s the loop it actually runs:

It starts as POST /orders. The Server’s auth middleware verifies her token and pulls out her user ID, then checks the request body makes sense. It packages the order into a request — with a unique request_id stamped on it — and appends it to the server_requests stream. Then the HTTP handler does something that surprises people the first time they see it: it waits.

Over on the Engine, a consumer is reading that stream. It picks up the message, turns it into a PlaceOrder command, and hands it to the actor. The actor, one command at a time, reserves Alice’s funds, runs the matching, and either rests the order on the book or fills it. Then it does two things: it writes the result back onto a reply stream keyed by that request_id, and it emits events — OrderPlaced, and if a trade happened, TradeExecuted — onto the db_events stream.

Back on the Server, another consumer is watching reply streams. It sees the result come back under Alice’s request_id, wakes up the HTTP handler that was waiting, and returns the JSON. Meanwhile, completely out of the critical path, the DB Worker consumes those db_events and writes the order, the trade, the balance change into Postgres.

That “send a request, wait for a reply keyed by ID” dance is a little request-response pattern wrapped up in a shared redis-client package. We’ll take it apart in its own chapter.

The part worth carrying with you

Look again at where the database sits in that story. The hot path — read the command, match it, reply — never touches Postgres. Writing to the database happens afterward, asynchronously, off to the side. If the database lags, or hiccups, or falls over for a minute, trades keep matching at full speed. The Engine’s in-memory state is the source of truth; the database is its mirror, catching up a beat behind.

That used to feel wrong to me — surely the database is the truth? But in a system that has to be fast and correct under load, you learn to flip it. Memory is truth, persistence is a consequence. It’s also exactly the trade-off that opens up the next set of questions: what if the reply gets lost? What if the Engine restarts and its memory is gone? Those aren’t holes I’m glossing over — they’re the whole point of later chapters on messaging reliability and on a write-ahead log that lets the Engine rebuild its state after a crash.

Where we go next

So that’s the lay of the land: three services with one job each, talking over Redis, and a hot path that stays clear of the database on purpose. With this map in your head, the code in the coming chapters won’t feel like wandering — you’ll always know which box you’re standing in.

From here the series goes hands-on, module by module, starting from an empty repository: the project scaffold, then the account model, then the matching engine itself. And as promised — every line in the open, free, no strings.