Skip to main content

Low-Level Design: Food Delivery App (Zomato/Swiggy-Style) in Java: Order State Machine, Rider Assignment and Concurrent Orders

Design a Zomato/Swiggy-style food delivery app in Java from scratch: an order lifecycle as a state table, exact-paise bills, three rider-assignment strategies, a FIFO dispatcher, race-free stock and kitchen capacity, and a seeded simulation. Every number is quoted from a committed transcript.

A food delivery app looks like one thing on a phone and is really four things that have to stay in agreement: an order that moves from “placed” to “delivered”, a kitchen that can only cook so much at once, a rider who can only be in one place, and a stock of dishes that can run out. Most of what goes wrong in a design (and in an interview) is two of these four disagreeing for a moment: two orders sold the last portion, two orders sent to the same rider, a customer cancelling at the instant the restaurant accepts. This article builds a small, complete version in plain Java, from a blank file to a simulation of a city. It starts at the very beginning (what a status is, why a table beats a pile of ifs) and works forward in one continuous line, so you can read it top to bottom without skipping. Every section ends with links to the exact file and the exact captured output the section is talking about, and the heavier material (why a lock and not a queue, what a real system would change) sits in the collapsible panels so it is there when you want it and out of the way when you do not. Two ideas are planted early and paid off late. The first is a single word, synchronized, in the class that owns an order’s status; it is the whole answer to the section on racing requests. The second is a stretch of the lifecycle (accepted, preparing, ready) during which a kitchen slot is held and a rider may be attached; it explains why cancelling has to give back three different things.
Versions this was built and run against. JDK 25.0.5.1 (Temurin, LTS; the java -version banner reads 2026-11-17), JUnit 6.1.3 (the latest GA on Maven Central, from maven-metadata.xml for junit-bom; 6.2.0-M1 is a milestone and the <latest> and <release> elements in that file both point at it), maven-surefire-plugin 3.6.1 and Maven 3.9.11. No frameworks and no runtime dependencies: all 965 lines under src/main are plain Java. Thirteen test classes write nineteen transcripts into output/ while asserting the same numbers; the module is food-delivery in the java-interview-lab repository. Three of the nineteen (the two race transcripts and the reject-versus-cancel one) depend on thread timing and say so in their first lines; the other sixteen came out identical on two consecutive full runs. This is a design exercise, not a production dispatch system, and the last section says where that line is.

Start with what has to be true, not with the classes

Before any code, write down the promises the system makes. Here they are for this module:
  • A customer can search restaurants near them, by dish, ranked by distance or by rating.
  • A customer can place an order. The bill is the food, a delivery fee that depends on distance, and tax, all in exact paise.
  • A restaurant can accept or reject an order, then prepare it. It can only cook a fixed number of orders at once.
  • Some dishes have limited portions. An order never takes a portion that is not there.
  • An accepted order gets a delivery rider. If every rider is busy, the order waits its turn.
  • The rider picks up the food and delivers it. The customer can cancel, but only until the kitchen starts cooking.
  • All of this stays correct when many people act at the same moment.
Left out on purpose: payments, real maps and road routing, ratings that update, multi-restaurant carts, coupons, persistence and push notifications. Each is a good follow-up question; none is needed to show the design. Here is the shape of the solution before the details. One class, FoodDeliveryService, is the only door into the system; behind it, each of the four things from the first paragraph has exactly one owner.
PricingPolicysubtotal + distance to billFoodDeliveryServicethe one door into the systemOrderListenerwho hears about changesOrderowns its statusInventorylimited portionsRestaurantmenu + kitchen slotsDispatcherqueue + rider claimsAssignmentStrategynearest / rated / idleDeliveryPartnerclaimed by CASOnly Order changes an order’s status.Everything else asks the service,and the service asks Order.
The sentence at the bottom left is the design rule that matters most: only Order changes an order’s status. The service, the dispatcher and the tests all ask it to; none of them reaches in and sets a field. That is what makes the next section possible, and it is what makes the race section short.

An order is a status that can only move along eight arrows

Think of a parcel tracker. A parcel is never “delivered” before it was “shipped”, and a delivered parcel never goes back to “packing”. An order works the same way: it has a status, and the business rules are really a list of which status may follow which. Eight statuses give sixty-four possible pairs (any status to any status). The rules allow exactly eight of them, drawn below. Everything else is a bug, and the whole job of this section is to make a bug impossible to express rather than merely unlikely.
PLACEDACCEPTEDPREPARINGREADYPICKED_UPDELIVEREDREJECTEDCANCELLEDkitchen slot held, and a rider may be attachedEight arrows in all. A terminal box (green or red) has none leaving it.Cancel is only drawn from PLACED and ACCEPTED: once the kitchen is cooking, it is too late.
Read the picture left to right as the happy path: placed, accepted by the restaurant, preparing, ready, picked up, delivered. The two red boxes are the ways an order ends without food arriving: the restaurant rejects it, or the customer cancels it. A box with no arrow leaving it is a terminal status; nothing can happen to that order any more. The dashed bracket across the top is the one to remember. From ACCEPTED to READY the kitchen has set a slot aside for this order and a rider may be on the way, so those are the statuses in which a cancellation has things to give back. The whole table is one switch in an enum. It reads like the diagram, which is the point:
    public Set<OrderStatus> allowedNext() {
        return switch (this) {
            case PLACED -> EnumSet.of(ACCEPTED, REJECTED, CANCELLED);
            case ACCEPTED -> EnumSet.of(PREPARING, CANCELLED);
            case PREPARING -> EnumSet.of(READY);
            case READY -> EnumSet.of(PICKED_UP);
            case PICKED_UP -> EnumSet.of(DELIVERED);
            case DELIVERED, REJECTED, CANCELLED -> EnumSet.noneOf(OrderStatus.class);
        };
    }

The code is in OrderStatus.java. Asking the table for every one of the sixty-four pairs gives this, written by StateMachineTest.java:

from \ to PLA ACC PRE REA PIC DEL REJ CAN 
PLACED    .   yes .   .   .   .   yes yes 
ACCEPTED  .   .   yes .   .   .   .   yes 
PREPARING .   .   .   yes .   .   .   .   
READY     .   .   .   .   yes .   .   .   
PICKED_UP .   .   .   .   .   yes .   .   
DELIVERED .   .   .   .   .   .   .   .   
REJECTED  .   .   .   .   .   .   .   .   
CANCELLED .   .   .   .   .   .   .   .   

legal moves: 8 of 64

Full transcript: output/02-state-machine.txt. Eight “yes” marks, and the three bottom rows are empty because those statuses are terminal.

A table nobody enforces is only documentation, so the second half is the class that enforces it. Order.moveTo checks the table, and if the move is not on it, throws and changes nothing. Notice the word synchronized on the method; it is the planted idea, and it is the reason two threads can never both move the same order at once.
    synchronized OrderEvent moveTo(OrderStatus next, long now) {
        if (!status.canMoveTo(next)) {
            throw new FoodDeliveryException.IllegalTransition(id, status, next);
        }
        if (next == OrderStatus.PICKED_UP && partnerId == null) {
            throw new FoodDeliveryException.NoPartnerAssigned(id);
        }
        OrderEvent event = new OrderEvent(id, status, next, now, partnerId);
        status = next;
        history.add(event);
        return event;
    }

From Order.java. Here is what a refused move looks like to the caller, and what the order looks like afterwards:

PLACED, markReady        : O-0001 cannot move from PLACED to READY; allowed from PLACED: [ACCEPTED, REJECTED, CANCELLED]
status afterwards         : PLACED

From output/02b-illegal-moves.txt; the message names the way out, which is what a support engineer reading a log at midnight wants. The same transcript shows cancelling from PREPARING and from DELIVERED refused in the same way.

Going deeper: why a table and not the State pattern, and why the rider check lives in Order Table versus State pattern. The Elevator article models a car as the State pattern: one class per state, each deciding what a button press means. That is the right tool when a state has different behaviour (an elevator with its doors open reacts to “move” differently from one that is idle). An order status has almost no behaviour of its own; what differs between states is only what may come next. For that, a table is shorter, shows the whole machine on one screen and is trivial to test exhaustively, as the 8-of-64 test above does. If statuses later grow real behaviour (a PREPARING state that computes a delay, say), that is the moment to promote them to classes. A legal move can still be refused. READY to PICKED_UP is on the table, yet the order refuses it if no rider has been assigned. That check sits inside moveTo beside the table check, so no caller can forget it. The transcript shows it with every rider offline:
all riders offline, order READY
pickUp: O-0001 has no delivery partner yet, so it cannot be picked up
status afterwards: READY

From output/02c-no-partner.txt. The order stays READY: the failed move changed nothing.

Going deeper
  • Ten more refused requests with their exact messages, and the proof they leave stock untouched: output/04-validation.txt.
  • Java’s EnumSet, used so the allowed-next list prints in a stable order.

Money is a whole number of paise, and a bill is three lines

Store prices as a long count of paise, never as a double of rupees. A double cannot hold 0.1 exactly, so sums of prices drift in the last digits, and a bill that is one paisa off is a support ticket. The Splitwise article shows the drift with real numbers; here it is simply a rule: money is a long, and only the printing code ever sees a decimal point. The bill has three lines. Food is the sum of price times quantity. Delivery is Rs 20 plus Rs 8 per kilometre, waived once the food reaches Rs 599. Tax is 5% of the food only, rounded half up to the paisa.
    public Bill price(long subtotalPaise, int distanceKm) {
        long fee = subtotalPaise >= FREE_DELIVERY_FROM ? 0 : BASE_FEE + PER_KM * distanceKm;
        long tax = (subtotalPaise * 5 + 50) / 100;
        return new Bill(subtotalPaise, fee, tax);
    }

From StandardPricing.java, behind a PricingPolicy interface because pricing is the part of a food app that changes every month. Six bills, including the two edges that matter:

food Rs 99.00     6 km  ->  food Rs 99.00 + delivery Rs 68.00 + tax Rs 4.95 = Rs 171.95
food Rs 547.00    3 km  ->  food Rs 547.00 + delivery Rs 44.00 + tax Rs 27.35 = Rs 618.35
food Rs 599.00   12 km  ->  food Rs 599.00 + delivery Rs 0.00 + tax Rs 29.95 = Rs 628.95
food Rs 598.99   12 km  ->  food Rs 598.99 + delivery Rs 116.00 + tax Rs 29.95 = Rs 744.94
food Rs 100.10    1 km  ->  food Rs 100.10 + delivery Rs 28.00 + tax Rs 5.01 = Rs 133.11
food Rs 100.30    1 km  ->  food Rs 100.30 + delivery Rs 28.00 + tax Rs 5.02 = Rs 133.32

From output/03-pricing.txt. Rs 599.00 of food ships free and Rs 598.99 pays Rs 116.00: that one paisa of difference at the threshold is exactly what a boundary test is for. The last two rows show the rounding: 5% of Rs 100.10 is 500.5 paise, which rounds up to Rs 5.01, and 5% of Rs 100.30 is 501.5 paise, which also rounds up, to Rs 5.02.

Going deeper: why (x * 5 + 50) / 100 is half-up, and what a real tax engine does Integer division in Java throws the remainder away, which rounds down. Adding half of the divisor first (50, when dividing by 100) turns “throw away” into “round to nearest, halves up”. That holds for non-negative amounts, which is all a bill has; a refund with a negative amount would need its own rule, and it is worth deciding that rule on purpose rather than inheriting whatever the arithmetic does. A real tax engine would price each line with its own rate (different kinds of items can carry different rates), round per line or per invoice according to the rule that applies, and keep the rule version with the order so a past bill can be reproduced. The interface seam is where that goes: the order stores the Bill it was given at placing time and never recomputes it.
Going deeper

Finding a restaurant is a filter and a sort

Search has two steps. First filter: keep restaurants that are open, within the customer’s radius, and (if a dish was typed) serve something that matches. Then sort what is left. The sort is the part that changes with a product decision, so it is a swappable rule: RestaurantRanking has NEAREST and TOP_RATED, and both end by comparing ids so that two equal restaurants never swap places between runs. Meera is at (4,4). Here are the same four restaurants ranked both ways, then a dish query, then a radius:
blank query, 10 km, NEAREST
  Biryani House  3 km  rating 4.4
  Dosa Corner    6 km  rating 4.6
  Pizza Point    6 km  rating 4.1
  Burger Lab     6 km  rating 3.9

blank query, 10 km, TOP_RATED
  Dosa Corner    6 km  rating 4.6
  Biryani House  3 km  rating 4.4
  Pizza Point    6 km  rating 4.1
  Burger Lab     6 km  rating 3.9

query "burger"
  Burger Lab: [Chicken Burger, Veg Burger]

radius 4 km: [Biryani House]
radius 4 km after Biryani House closes: 0 results

From output/05-search.txt, written by SearchTest.java. Three restaurants tie at 6 km and the id decides their order: Dosa Corner, Pizza Point, Burger Lab. Closing Biryani House removes it from the results at once, because search reads the live open flag.

Going deeper: what this search leaves out Distance here is Manhattan distance on a grid, in whole kilometres: |dx| + |dy|. Roads are closer to a grid than to a straight line, it is cheap, and integer distances make every transcript exactly repeatable. A real system would use road-network travel time, and it would not scan every restaurant: it would keep restaurants in a spatial index (a grid of cells, or a geohash) and only look at the cells around the customer. The interface does not change; only the line that finds candidates does. A ranking that mixes several signals (distance, rating, how busy the kitchen is, an estimated delivery time) is usually a weighted score. Keep the weights in one place and keep the id tiebreak last, or results will shuffle between refreshes and users will notice.
Going deeper

Placing an order: check everything first, take things last

Placing an order is where the system makes its first promise, so the order of the steps matters. Validate everything first; reserve stock last. If the cart is empty, the restaurant is closed, an item is not on its menu or the address is too far, the request fails before anything has been taken, so there is nothing to give back. The entry point also takes an idempotency key: a string the app generates once per tap. The same key always returns the same order. A customer who double-taps, or an app that retries after a timeout, must not get two orders and two charges.
    public Order placeOrder(String idempotencyKey, String customerId, String restaurantId, Map<String, Integer> items) {
        if (idempotencyKey == null || idempotencyKey.isBlank()) {
            throw new FoodDeliveryException.InvalidOrder("an idempotency key is required");
        }
        return byIdempotencyKey.computeIfAbsent(idempotencyKey, k -> create(customerId, restaurantId, items));
    }

From FoodDeliveryService.java. Ten bad requests and the exact message for each, written by ValidationTest.java:

blank key                InvalidOrder: an idempotency key is required
unknown customer         NotFound: customer C9 not found
unknown restaurant       NotFound: restaurant R9 not found
empty cart               InvalidOrder: the cart is empty
item from another menu   InvalidOrder: Biryani House has no item p1
quantity zero            InvalidOrder: quantity for Chicken Biryani must be 1 to 20, got 0
quantity 21              InvalidOrder: quantity for Chicken Biryani must be 1 to 20, got 21
24 km away               InvalidOrder: Pizza Point is 24 km away; we deliver up to 15 km
more than the stock      OutOfStock: b1: wanted 6, only 5 left
closed restaurant        Dosa Corner is closed

From output/04-validation.txt.

And here is the idempotency key doing its job, including sixteen threads sending the same key at the same instant:
same key twice: O-0001 and O-0001, stock left 8
new key        : O-0002, stock left 6
16 threads, one key: distinct orders 1, stock left 5

From output/12-idempotency.txt, written by IdempotencyTest.java. One order, and stock reduced once.

All or nothing, across lines. A cart with two lines where the second is short must not leave the first line reserved. The validation transcript ends with exactly that case: a two-line cart where the second line is short leaves Veg Biryani stock at 3, unchanged. The reservation checks every line before it changes any (the section on racing requests shows the code).
Going deeper: how the idempotency key works, and what it does not cover ConcurrentHashMap.computeIfAbsent runs the creating function at most once per key, even when sixteen threads arrive together; the others wait for the first to finish and receive its result. If the function throws (out of stock, say), no mapping is stored, so a later retry with the same key tries again. That is the behaviour you want for a failed attempt and a different one from caching the failure. Two limits to know. The key map here lives in memory, so it forgets on restart; a real service stores keys in the database next to the order, with an expiry, and rejects a repeated key whose request body differs. And the ConcurrentHashMap Javadoc warns that other updates to the map may be blocked while the function runs, which is fine for a short in-memory function and a reason not to call a slow service inside it.
Going deeper

One order, start to finish

Now the pieces can be shown together. Meera at (4,4) orders two Chicken Biryani and a Raita from Biryani House, 3 km away. A listener attached to the service records every status change and every rider assignment, which is the Observer pattern: the order code publishes events and does not know whether anything is listening, so a notification sender, an analytics feed and a live tracking screen can all be added without touching it.
Meera (4,4) orders from Biryani House (2,3), 3 km away
  food Rs 547.00 + delivery Rs 44.00 + tax Rs 27.35 = Rs 618.35

Event log
  t=00  O-0001  - -> PLACED
  t=02  O-0001  PLACED -> ACCEPTED
  t=02  O-0001  partner P1 assigned
  t=03  O-0001  ACCEPTED -> PREPARING
  t=14  O-0001  PREPARING -> READY
  t=15  O-0001  READY -> PICKED_UP
  t=21  O-0001  PICKED_UP -> DELIVERED

After delivery: Imran is AVAILABLE at (4,4), idle since minute 21, deliveries 1

From output/01-happy-path.txt, written by LifecycleTest.java. Read the bill first: food Rs 547.00 is 2 × Rs 249.00 plus Rs 49.00; delivery is Rs 20 plus 3 km × Rs 8 = Rs 44.00; tax is 5% of food, Rs 27.35. In the log, the rider appears at the same minute as the acceptance: the moment the restaurant says yes, the dispatcher looks for a rider, which is why the next section matters. Imran ends the trip at Meera’s door, (4,4), free again and idle since minute 21, which is exactly the data the strategies below use.

Picking a rider is a strategy; the dispatcher makes it safe

Two separate questions hide inside “assign a rider”, and keeping them separate is the design. Which rider would we like? is a policy, and it changes with the business, so it is a one-method interface: given the restaurant and the list of free riders, return one. Can we actually have that rider? is a matter of correctness and is handled by the dispatcher, which claims the rider atomically and only then tells the order about it. Take one order and three free riders and ask three different policies. The picture shows who is where; the transcript shows who each policy picks.
Biryani HouseP1P2P31 square = 1 km, distance counted along the gridSame order, same ridersP1 Imran1 km away, rating 4.2, idle since minute 30P2 Kavya5 km away, rating 4.8, idle since minute 20P3 Sunil3 km away, rating 4.5, idle since minute 10Who gets the jobnearest→ P1 (closest)rated within 5 km→ P2 (best rating of the three)longest idle→ P3 (waited longest)
The dashed lines are the distances to the restaurant: 1 km, 5 km and 3 km. Nearest takes Imran because he is closest. Rated within 5 km looks only at riders within five kilometres (all three) and takes the best rating, Kavya. Longest idle ignores distance and takes whoever has waited longest for a job, Sunil. Same order, same riders, three answers, and none of them is wrong: each optimises something different.
    public Optional<DeliveryPartner> pick(Point restaurant, List<DeliveryPartner> available) {
        return available.stream().min(
                Comparator.comparingInt((DeliveryPartner p) -> p.location().km(restaurant)).thenComparing(DeliveryPartner::id));
    }

The simplest strategy, from NearestPartner.java; the other two are the same shape in RatedWithinRadius.java and LongestIdle.java. The pick, as the test records it:

Order pickup: Biryani House (2,3)
  P1 Imran  at (3,3)  1 km away  rating 4.2  idle since minute 30
  P2 Kavya  at (6,2)  5 km away  rating 4.8  idle since minute 20
  P3 Sunil  at (2,6)  3 km away  rating 4.5  idle since minute 10

nearest        -> P1
rated<=5km     -> P2   (all three are within 5 km, so the best rating wins)
rated<=2km     -> P1   (only P1 is within 2 km)
longest-idle   -> P3   (P3 has waited longest)

From output/06-assignment.txt, written by AssignmentTest.java. Each rule ends by comparing ids so a tie is never decided by chance.

When an order is accepted, the service hands it to the Dispatcher, which keeps a first-in-first-out queue of orders still waiting for a rider. Every time something changes (an order arrives, a rider is freed, a rider comes online) the dispatcher drains the queue: it looks at the order at the head, asks the strategy for a rider, claims that rider, and moves on until nobody is free.
    private void drain() {
        synchronized (drainLock) {
            while (true) {
                Order head = pending.peek();
                if (head == null) return;
                if (!head.needsPartner()) {      // cancelled or already served while it waited
                    pending.poll();
                    continue;
                }
                DeliveryPartner claimed = claimFor(head);
                if (claimed == null) return;     // nobody free: the head waits, and so does everyone behind it
                pending.poll();
                if (head.tryAssign(claimed.id())) {
                    onAssigned.accept(head, claimed);
                } else {
                    claimed.unclaim();           // the order was cancelled between the check and the assignment
                }
            }
        }
    }

From Dispatcher.java. Two comments in the code are doing real work. If the head of the queue cannot get a rider, everyone behind it waits too, which is what first-in-first-out means. And an order cancelled while it waited is skipped when its turn comes, instead of being handed a rider it no longer needs. One rider, three orders, and what frees the queue:

three orders accepted, one rider (P1) online
  O-0001 rider P1
  O-0002 rider null
  O-0003 rider null
  waiting: [O-0002, O-0003]

O-0001 delivered at minute 20, P1 free again
  O-0002 rider P1
  O-0003 rider null
  waiting: [O-0003]

P3 comes online at minute 20
  O-0003 rider P3
  waiting: []

From output/07-dispatch-queue.txt, written by DispatchQueueTest.java. The older waiting order (O-0002) gets the rider before the newer (O-0003); when a third rider comes online the last order is served and the queue is empty.

Going deeper: why one lock plus a compare-and-set, and what blocks at the head of the queue Two layers of safety, on purpose. The drain runs inside one lock, so only one thread rearranges the queue at a time. Claiming the rider inside it is still a compare-and-set (shown in the racing section), because the dispatcher is not the only thing that touches a rider: a rider can go offline at the same instant. If the claim fails, the dispatcher removes that rider from its candidate list and asks the strategy again, as claimFor does:
    private DeliveryPartner claimFor(Order order) {
        List<DeliveryPartner> candidates = new ArrayList<>(partners.stream().filter(DeliveryPartner::isAvailable).toList());
        while (!candidates.isEmpty()) {
            DeliveryPartner pick = strategy.pick(order.pickup(), candidates).orElse(null);
            if (pick == null) return null;
            if (pick.tryClaim()) return pick;
            candidates.remove(pick);             // somebody else got there first; choose again from the rest
        }
        return null;
    }

From Dispatcher.java.

Head-of-line blocking. Strict first-in-first-out is fair and easy to reason about, but it has a cost: a far-away order at the head can keep a nearer order behind it waiting even when a rider could serve the second one right now. A more elaborate dispatcher can batch orders, skip ahead, or match within zones. The honest summary is that FIFO is the simplest rule that is fair, and the simulation below shows when the choice of rider matters at all. One lock does not scale forever. A single drain lock is fine for a module and for one city; the usual next step is one dispatcher per delivery zone, so zones never wait for each other. The strategy interface and the claim-by-compare-and-set carry over unchanged.
Going deeper

Cancelling and rejecting must give everything back

An order takes things as it moves: stock when it is placed, a kitchen slot when it is accepted, a rider when one is assigned. Anything it takes, it must return when it ends early, or the restaurant slowly “fills up” with orders that no longer exist. This is where the dashed bracket in the state diagram pays off: what has to be returned depends on where the order was when it was cancelled.
    public Order cancel(String orderId) {
        Order order = order(orderId);
        OrderEvent event = order.moveTo(OrderStatus.CANCELLED, clock.now());
        publish(event);
        stock.release(order.restaurantId(), order.quantities());
        if (event.from() == OrderStatus.ACCEPTED) {
            restaurant(order.restaurantId()).releaseKitchenSlot();
            if (event.partnerId() != null) {
                DeliveryPartner partner = partner(event.partnerId());
                dispatcher.partnerFreed(partner, partner.location(), clock.now());
            }
        }
        return order;
    }

From FoodDeliveryService.java. The status change comes first and decides everything else: event.from() says which status the order was in. Cancelled from PLACED, only stock was held. Cancelled from ACCEPTED, there is also a kitchen slot and possibly a rider. The transcript follows all three quantities through a cancel, an accept-then-cancel and a reject:

start                       : stock b1=10, kitchen slots used=0, P1=AVAILABLE
placed 3 x b1               : stock b1=7, kitchen slots used=0, P1=AVAILABLE
cancelled while PLACED      : stock b1=10, kitchen slots used=0, P1=AVAILABLE
placed 4, accepted          : stock b1=6, kitchen slots used=1, P1=BUSY  (rider P1)
cancelled while ACCEPTED    : stock b1=10, kitchen slots used=0, P1=AVAILABLE
placed 2, rejected          : stock b1=10, kitchen slots used=0, P1=AVAILABLE

From output/08-cancel-reject.txt, written by CancelRejectTest.java. After each ending the three numbers are back where they started: stock 10, no kitchen slots used, rider available.

Going deeper: why a late cancel is refused, and what a real app does instead From PREPARING the table has only one arrow out (to READY), so a cancel is refused with the exact message shown earlier. That is a business rule written as data: the kitchen has started cooking, so the food exists. A real app usually still lets the customer cancel, but charges a fee and tells the restaurant; in this design that would be a new status or a flag on CANCELLED, plus a refund calculation, and it would be one more row in the table rather than a new if somewhere. Compensation ordering. The order moves to CANCELLED first and the returns happen after, so a failure while returning stock leaves a cancelled order with stock to reclaim (recoverable by a retry or a sweep) rather than a live order with no stock behind it. The reverse order would leave customers holding orders the restaurant cannot fulfil.
Going deeper

Many people at once: four races, and the one idea behind all of them

Everything so far works if one person uses the app at a time. A real app is the opposite, so this section takes the four places where two requests can collide, shows each failure, and shows the fix. They have one idea in common, and it is worth stating before the code: a check and the action that depends on it must happen as one step. “Is there stock? Then take it” is two steps; if anything can happen between them, the check may be out of date by the time it is acted on. The picture is the smallest possible version: one portion left, two buyers.
Thread AThread Bread stocksees 1write 0sold oneread stocksees 1write 0sold onetimeBoth reads happen before either write, so each thread believes the last portion is its own: two sold from a stock of one.
Both threads read “1” before either one writes “0”, so both decide the last portion is theirs. Nothing in either thread’s code is wrong when read alone; the bug exists only in the interleaving, which is why it passes a single-user test and fails on a busy evening.

Race 1: the last portions

The tempting implementation uses a thread-safe map and checks before it writes. Every single call on a ConcurrentHashMap is safe; the sequence of a read, a compare and a write is not. This is the version, which lives in the tests only because it exists to be shown failing:
    public void reserve(String restaurantId, Map<String, Integer> quantities) {
        for (var e : quantities.entrySet()) {
            String key = restaurantId + "/" + e.getKey();
            Integer have = stock.get(key);
            if (have == null) continue;
            if (have < e.getValue()) throw new FoodDeliveryException.OutOfStock(e.getKey() + ": only " + have + " left");
            stock.put(key, have - e.getValue());
        }
    }

From support/NaiveInventory.java. The fix puts the check and the write inside one lock on that restaurant’s stock, and checks every line before it changes any (which is what keeps a short second line from leaving the first one reserved):

    public void reserve(String restaurantId, Map<String, Integer> quantities) {
        Map<String, Integer> stock = stockOf(restaurantId);
        synchronized (stock) {
            for (var e : quantities.entrySet()) {
                Integer have = stock.get(e.getKey());
                if (have != null && have < e.getValue()) {
                    throw new FoodDeliveryException.OutOfStock(
                            e.getKey() + ": wanted " + e.getValue() + ", only " + have + " left");
                }
            }
            for (var e : quantities.entrySet()) {
                stock.computeIfPresent(e.getKey(), (k, have) -> have - e.getValue());
            }
        }
    }

From Inventory.java. The test sends sixteen buyers at ten portions, released at the same instant, 5,000 times, against both versions:

Timing dependent: the naive counts differ from run to run; the locked counts never do.

naive  (check, then write): rounds that sold more than 10: 21 of 5000, worst round sold 12
locked (check and write together): rounds that oversold: 0, undersold: 0 of 5000

From output/09-stock-race.txt, written by StockRaceTest.java. The locked version sold exactly ten portions in every one of 5,000 rounds. The naive version oversold in some rounds; how many, and by how much, changes from run to run, which is the nature of a race and the reason the transcript says so before the numbers. The test asserts only the locked result.

Race 2: one rider, many orders

The same shape appears at the rider. “If the rider is available, mark them busy” is a check followed by an action. The fix is a single hardware-level step: a compare-and-set that changes the status from AVAILABLE to BUSY only if it is still AVAILABLE, and tells you whether it did.
    public boolean tryClaim() {
        return status.compareAndSet(PartnerStatus.AVAILABLE, PartnerStatus.BUSY);
    }

From DeliveryPartner.java. Now the honest part of this experiment. Here is the naive version, and the test runs it two ways:

    private static final class NaiveRider {
        private volatile PartnerStatus status = PartnerStatus.AVAILABLE;
        private final boolean workInTheGap;

        NaiveRider(boolean workInTheGap) { this.workInTheGap = workInTheGap; }

        boolean claim() {
            if (status == PartnerStatus.AVAILABLE) {
                if (workInTheGap) Thread.yield();   // stands in for the real work between "is he free?" and "he is ours": a DB read, a log call
                status = PartnerStatus.BUSY;
                return true;
            }
            return false;
        }
    }

From PartnerClaimTest.java.

Timing dependent: the naive count differs from run to run; the compare-and-set count never does.

naive, check then write, nothing in between: rounds where more than one order got the rider: 0 of 5000, most winners in one round 1
naive, with a yield between the check and the write: rounds where more than one order got the rider: 389 of 5000, most winners in one round 7
atomic (compare-and-set), no gap needed: rounds with anything other than one winner: 0 of 5000

From output/10-partner-claim.txt. Look at the first naive line: with nothing between the check and the write, sixteen threads fought over one rider 5,000 times and not once did two of them win (in every run I made). The window between the two lines is only a few instructions wide, and the machine simply never landed in it. If this were the only test, the naive code would have passed it. The second naive line adds one Thread.yield() between the check and the write, standing in for what real code has there (a database read, a log call), and now a large share of rounds double-book the rider, with up to seven of sixteen threads believing they own it. The compare-and-set version had exactly one winner in every round, with no help needed.

A concurrency test that passes proves very little. The naive rider claim passed 5,000 rounds with zero failures when the window was tiny and failed hundreds of rounds the moment there was real work in the gap. When you test for a race, widen the window on purpose, run many rounds, and put the correct version through the same torture. Assert on the correct version only: a test that asserts a race will happen is itself flaky, which is why the naive counts here are printed and never asserted.

Race 3: the kitchen’s capacity

A kitchen that cooks two orders at a time must never accept a third, no matter how many staff tap “accept” together. Here the thing being protected is a counter, so the check and the increment must be one step. The loop below reads the count, refuses if it is full, and otherwise tries to swap the count for count plus one; if another thread changed it in the meantime, the swap fails and the loop reads again.
    boolean tryReserveKitchenSlot() {
        while (true) {
            int current = activeOrders.get();
            if (current >= capacity) return false;
            if (activeOrders.compareAndSet(current, current + 1)) return true;
        }
    }

From Restaurant.java. Fifty orders for Burger Lab (capacity 2), sixteen threads accepting at once, 300 rounds:

rounds: 300
accepted per round: 2 (every round)
refused per round : 48 (every round)
totals: accepted 600, refused 14400

From output/11-accept-capacity.txt, written by AcceptRaceTest.java. Exactly two accepted and forty-eight refused in every round, and the refused orders stay PLACED so they can be retried. The service takes the slot before moving the order and gives it back if the move fails, so a slot is never held for an order that could not be accepted.

Race 4: reject and cancel at the same instant

The restaurant presses “reject” at the moment the customer presses “cancel”. Both start from PLACED, both are legal on their own, and both would return the stock. Exactly one may win, and the stock must come back once, not twice. This is where the planted synchronized on Order.moveTo pays off: the two calls are forced into a line, the first one changes the status to a terminal one, and the second finds it is no longer on PLACED, fails the table check and throws before it can touch the stock.
The thread released first tends to win, so the two roles swap threads every round to exercise both orders.
Who wins depends on timing; that exactly one wins, and that stock comes back once, never does.

rounds: 2000, reject won 1000, cancel won 1000

From output/11b-reject-vs-cancel.txt, written by AcceptRaceTest.java. Two thousand rounds; in each, exactly one side succeeded, and stock was back at 10, never 13. The roles swap threads every round because the thread released first tends to win; the split between reject and cancel is therefore a property of the test, not of the code, and the assertions are about the two things that must always hold.

One last check puts the dispatcher under load: 200 orders accepted from eight threads against 20 riders.

orders with a rider: 20
distinct riders used  : 20
still waiting        : 180

From output/10b-dispatch-under-load.txt. Exactly twenty orders got a rider, twenty different riders were used, and 180 orders are waiting. No rider was given two jobs and no order was given two riders.

Going deeper: lock, compare-and-set or queue, and how these races look on a database Which tool for which race. A lock (synchronized) protects a group of steps that must be seen together: the stock check across several cart lines. A compare-and-set protects a single value: a rider status, a counter. A queue protects an ordering: who is served first. Reaching for the smallest tool that covers the invariant keeps the code readable and the contention low; the stock lock is per restaurant, so a busy kitchen never slows a quiet one. On a database the same four races exist, and the fixes are the same ideas in different clothes. A stock row is decremented with a conditional update (update ... set qty = qty - 1 where qty >= 1) and the number of rows changed says whether it worked, which is the compare-and-set. An order status changes with where status = 'PLACED', the same expected-status check as the table. A rider claim is a conditional update on the rider row. The BookMyShow article compares naive, pessimistic and optimistic versions of exactly this on a real database (H2) and is the place to go for that side. What these fixes do not cover. They make each step atomic inside one process. Two application servers would each have their own lock and their own counter, so a multi-server system must move these checks into the shared database or a shared store. Nothing here is distributed.
Going deeper

Which rider strategy is best? It depends on whether there is a choice

Three strategies, one question. To answer it fairly, the module includes a small city: 12 restaurants and some riders scattered on a 20 by 20 km grid, orders arriving over 240 minutes, a seeded random generator so every strategy faces the identical orders, and riders travelling 2 minutes per kilometre. Each run goes on until the last order is delivered. The simulation uses the real service from the sections above (it places, accepts, prepares, picks up and delivers through the same methods), so it also works as an end-to-end test. The bars show the average minutes from placing an order to the door, at three levels of load.
26.426.435.8Comfortable: 40 riders, 200 orders30.429.642.0Tight: 30 riders, 200 orders93.198.593.1Saturated: 30 riders, 300 ordersnearestrated within 5 kmlongest idleAverage minutes from placing an order to the door. Same orders for every bar in a group.
Read each group separately. With spare riders (left), nearest and rated-within-5-km are equal and best, and longest-idle is clearly slower. With fewer riders (middle) longest-idle is again the slowest by a wide margin. With too few riders (right), where the waiting queue stands at dozens of orders, the bars are nearly the same height, and nearest and longest-idle are identical to the decimal. The full table behind the chart has more columns:
Comfortable: 40 riders, 200 orders
  strategy         avg min  p90 min  empty km  food wait  rider wt max queue per rider
  nearest             26.4       34       4.1        0.4       6.3         0     2-8
  rated<=5km          26.4       34       4.3        0.4       5.9         0     0-8
  longest-idle        35.8       54      10.9        9.8       2.2         0     4-7

Tight: 30 riders, 200 orders
  strategy         avg min  p90 min  empty km  food wait  rider wt max queue per rider
  nearest             30.4       43       7.3        4.5       3.9         1     4-8
  rated<=5km          29.6       40       6.8        3.6       4.0         0     4-9
  longest-idle        42.0       59      12.5       16.1       1.4        13     5-8

Saturated: 30 riders, 300 orders
  strategy         avg min  p90 min  empty km  food wait  rider wt max queue per rider
  nearest             93.1      147      12.6       67.4       0.5        90     8-12
  rated<=5km          98.5      156      13.0       72.8       0.4        99     7-12
  longest-idle        93.1      147      12.6       67.4       0.5        90     8-12

From output/13-simulation.txt, written by SimulationTest.java. The columns after the two minute figures are average kilometres a rider rides empty to the restaurant, average minutes ready food waits for a rider, average minutes a rider waits at the restaurant for the food, the longest the waiting queue got, and deliveries per rider (fewest to most).

Three readings, each backed by the table. First, when riders are plentiful, distance is the thing that matters: longest-idle sends riders 10.9 km on average to a restaurant against 4.1 km for nearest, and the food waits 9.8 minutes for a rider against 0.4. Second, fairness has a price and a benefit: longest-idle spreads work more evenly (4 to 7 deliveries per rider, against 2 to 8 for nearest), at the cost of slower deliveries. Third, when there is a standing queue, the strategy stops mattering: a rider is freed, exactly one rider is free, and there is nothing to choose between. The delay is set by how many riders there are, not by how cleverly one is picked, and the fix for a saturated city is more riders or fewer orders, not a better formula. The test asserts all three readings, so they fail the build if the code changes them.
Going deeper: what the simulation simplifies, and how to read it with suspicion What is simplified. Orders arrive uniformly at random, customers live within 6 km (in each direction) of the restaurant they order from, preparation takes 8 to 20 minutes, riders never go offline, and travel time is exactly 2 minutes per kilometre with no traffic. One seed (42) was used for the transcript. None of these make the comparison between strategies unfair, since they are identical for all three, but they do mean the absolute numbers are properties of this toy city and nothing more. The number to distrust is the cross-over. The point at which the strategies converge depends on the ratio of riders to orders in this city. The qualitative result (choice matters only while there is a choice) is the part that generalises; the particular figures are not a claim about any real service. Variations worth trying. A hybrid that picks nearest but skips riders who have had far more deliveries than the average. A rule that holds a rider back for a restaurant that is about to have food ready (the table shows riders waiting at the restaurant for food in the comfortable case). Different seeds, to see how stable the ordering is; the generator is in Simulation.java.
Going deeper
  • The simulation loop and its metrics: Simulation.java.
  • Choosing a dispatch policy by simulating it first, with a different domain: the Elevator article compares round-robin, nearest-car and ETA dispatch on seeded traffic.

Mistakes that look fine until they are not

  • Setting a status field directly. The moment two places can write order.status = ..., the table is advice. Keep the setter private and the only door a method that checks the table (section on the eight arrows).
  • Check-then-act on shared state. A stock check followed by a decrement, a rider check followed by a claim, a capacity check followed by an increment: each passes a single-user test and fails under load (the four races).
  • Trusting a race test that has never failed. The naive rider claim passed 5,000 rounds until real work was put in the gap.
  • Forgetting what a cancel must return. Stock is held from placing, the kitchen slot from accepting, the rider from assignment. Release by the status the order was in, not by habit (section on giving everything back).
  • Money in a double. One paisa wrong at a threshold becomes a support ticket (the bill section).
  • No idempotency key. A retry after a timeout creates a second order and a second charge.
  • Letting ties decide. Two equally good restaurants or riders must still come out in a stable order, or results shuffle between refreshes and tests become flaky.

Should you build it this way?

For an interview, or to learn, yes. For production, treat it as the shape and not the system. The design (one owner of status, strategies behind interfaces, atomic claims, compensation on cancel) carries over to a real service. The implementation does not: state is in memory, so nothing survives a restart; the locks and counters protect one process, not a fleet; there is one dispatcher for the whole city; distance is a grid; and there are no payments, no maps and no persistence. A production version would keep orders and stock in a database with the conditional updates described above, dispatch per zone, estimate delivery time from real road data, and write the order history to a durable event log.

The thing worth keeping from this exercise is the habit rather than the code: draw the lifecycle first, give each fact one owner, and for every pair of requests that could collide ask what happens if they arrive together.
Going deeper: a 45-minute plan for presenting this, and the follow-up questions to expect A good order for a 45-minute round: requirements and what you are leaving out (5 minutes); the class diagram and the “only Order changes status” rule (5); the state table and why it beats scattered ifs (7); placing an order, validation and idempotency (5); the rider strategy interface and the dispatcher queue (8); the stock race, drawn as the two-thread picture, and its fix (10); then what you would change for a database (5). Questions that tend to follow: how would you add surge pricing (a new PricingPolicy); how would you batch two orders for one rider (the dispatcher claims a rider for a list of orders, and the state table gains no new arrow); how do you estimate delivery time (replace distance with a travel-time service behind the strategy); what happens when a rider goes offline mid-delivery (a reassign path, which is a new arrow in the table and a new event); how do you shard (by delivery zone); how do you test concurrency (the barrier harness above, with widened windows).

Further reading

No Comments yet!

This site uses Akismet to reduce spam. Learn how your comment data is processed.