Design a Food Delivery Platform: Orders, Restaurants and Delivery Partners

At 8:30 p.m. on a Friday, a customer orders biryani. For the next 35 minutes, three parties who never talk to each other directly must stay perfectly coordinated: the restaurant must accept and cook it, a delivery partner must be nearby exactly when it is ready, and the customer must see accurate progress the whole time. If the restaurant's tablet loses Wi-Fi, if the partner's bike breaks down, or if payment confirmation arrives late, the system must notice and recover, usually without a human, and at dinner peak it does this for thousands of orders a minute.

The ride-hailing design (article 41) solved "find someone nearby and assign them". Food delivery adds a long-running, multi-party workflow with real-world timing. This case study focuses on that workflow: the order state machine, the saga that drives it, and dispatch timed to food readiness. The design is generic and illustrative; it does not describe any particular company's systems.

• How to scope a three-sided marketplace and estimate its peaks.
• Discovery and menus as cached read models.
• A safe checkout, and the order state machine with a runnable example.
• An orchestrated saga with timeouts and compensations.
• Dispatch timed to food readiness, and order batching.
• Live tracking, notifications, dinner-peak load and failures.

Customers browse nearby restaurants and menus, place an order and pay. The restaurant accepts and prepares it. A delivery partner picks it up and delivers it. Everyone sees status and timing in real time. Cancellations and refunds follow clear rules.

Functional requirements: discover restaurants and menus; build a cart and place an order; pay; restaurant accept, prepare and mark ready; assign and track a partner; deliver; cancel and refund per policy; notify all parties.

Non-functional requirements

Orders: 3 million/day -> about 35/s averageDinner peak: 40% of orders in 3 hours -> peak factor 0.4 x 24 / 3 = 3.2 -> about 110 orders/sOrder events (state changes, assignments, ETA updates): about 15 per order -> about 1,700/s at peakBrowsing: 30 million app sessions/day x 20 API calls -> 600 million/day,  about 7,000/s average, about 22,000/s at peak (mostly cacheable)Delivery partners online at peak: 300,000, location every 4 s -> 75,000 location updates/sActive orders at peak: 110/s x 40 minutes average lifecycle = about 264,000 concurrent ordersRestaurants: 300,000; menus about 100 items each -> 30 million menu items (small data, read often)

Conclusions: order volume is moderate (about 110 per second) but each order is a long-lived workflow with many events and external actors; browsing is high-volume but cacheable; partner locations are a high-rate stream, handled exactly as in article 41.

Customer:  GET  /v1/restaurants?lat=..&lng=..&cuisine=..&cursor=..     -> nearby, open, with delivery ETA (cached)  GET  /v1/restaurants/{id}/menu                              -> menu with availability (cached, short TTL)  POST /v1/orders   Idempotency-Key: ...       { restaurant_id, items: [{item_id, qty, options}], address_id, quoted_total, payment_method_token }       -> 201 { order_id, status: "PLACED", total } | 409 price or availability changed (with details)  GET  /v1/orders/{id}                                         -> status, ETA, partner location (when assigned)  POST /v1/orders/{id}/cancellation                            -> per policy; refund detailsRestaurant (tablet app, persistent connection plus HTTP):  NEW_ORDER (push) ; POST /v1/restaurant/orders/{id}/accept {prep_minutes} | /reject {reason}  POST /v1/restaurant/orders/{id}/ready ; PUT /v1/restaurant/items/{itemId}/availabilityDelivery partner (as in article 41):  LOCATION (stream) ; OFFER (push) ; POST /v1/offers/{id}/accept ; POST /v1/deliveries/{id}/picked-up | /delivered

The checkout includes the quoted total the customer saw; the server recomputes the price and rejects the order with 409 if it changed, rather than silently charging a different amount.

Catalogue (owned by the restaurant service; source of truth):  restaurants (restaurant_id, location, cell, hours, status open/busy/closed, avg_prep_minutes)  menu_items  (item_id, restaurant_id, name, price_paise, available, version)Read models (fed by events, cached):  restaurants_by_cell (cell, ranking signals) ; menu documents per restaurant ; search indexOrders (owned by the order service, partitioned by city):  orders      (order_id PK, customer_id, restaurant_id, city, status, total_paise, version,               idem_key UNIQUE per customer, created_at, eta_at)  order_items (order_id, line_no, item_id, name, unit_price_paise, qty)   -- prices copied at purchase  order_saga  (order_id PK, step, deadline_at, attempts, last_error)       -- orchestrator state  outbox      (event_id, aggregate_id = order_id, type, payload)Dispatch (owned by the dispatch service, per city):  deliveries  (delivery_id, order_id UNIQUE, partner_id, status, pickup_eta, dropoff_eta)  partner_assignment (partner_id PK, current_deliveries, version)          -- reservation record, as in article 41

The order service owns order state; the restaurant service owns menus; payment and dispatch own their data; they communicate by commands and events (articles 26 and 27).

One application and one database: the order is inserted, the payment provider called inline, the restaurant polls for new orders, and an operator assigns delivery partners by phone. It works for a small town. At city scale it fails on every axis: polling tablets lag, inline payment calls make checkout fragile, manual dispatch cannot keep up at dinner, and nothing notices when a restaurant silently never accepts.

1. Coordination: an order waits on three independent parties; each can be slow, offline or say no.
2. Silent stalls: a restaurant tablet offline means an order that nobody is cooking.
3. Duplicate and out-of-order events: apps retry, webhooks repeat, a "ready" tap arrives after a cancellation.
4. Dispatch timing: a partner who arrives too early waits (wasting partner time); too late, food gets cold.
5. Dinner peak: three times average load, all at once, in every city.
6. Stale menus: a sold-out item ordered anyway.

Browsing dominates request volume and changes slowly, so it is served from read models built from catalogue events (CQRS, article 27; Microsoft's CQRS guidance describes read models kept in sync by events and accepting eventual consistency (CQRS pattern)):

• Nearby restaurants: indexed by geographic cell (H3 or similar, as in article 41 (H3)), with ranking signals and estimated delivery times, cached per cell for a minute.
• Menus: one document per restaurant, cached, with a short TTL and event-driven invalidation when the restaurant marks an item unavailable.
• Search: a search index fed by catalogue events.
• Availability and price are re-checked at checkout against the source of truth, so a stale menu never results in a wrong charge.

1. Validate the cart against the catalogue: items exist, are available, prices match the quote.
2. In one transaction in the order service: insert the order (PLACED) and items with copied prices, the saga row, and an outbox event OrderPlaced (the outbox pattern from article 21 (Transactional outbox)). The idempotency key makes a double tap return the same order.
3. Return 201 with the order id. Everything else is asynchronous.

PLACED -> PAID -> ACCEPTED -> PREPARING -> READY -> PICKED_UP -> DELIVERED   \        \        \            \    `--------`--------`------------`--> CANCELLED   (per policy, with compensation)

Each transition is a conditional update on the current state, exactly as in the payment design (article 39). This Java program applies a realistic stream of events, including a duplicate payment webhook and a "ready" tap that arrives after the customer cancelled, and shows which ones the state machine accepts.

// File: OrderStateMachine.javaimport java.util.EnumSet;import java.util.Map;import java.util.Set;public class OrderStateMachine {    enum State { PLACED, PAID, ACCEPTED, PREPARING, READY, PICKED_UP, DELIVERED, CANCELLED }    // The only legal moves. Anything else is rejected, which makes duplicate and late events harmless.    static final Map<State, Set<State>> ALLOWED = Map.of(            State.PLACED, EnumSet.of(State.PAID, State.CANCELLED),            State.PAID, EnumSet.of(State.ACCEPTED, State.CANCELLED),            State.ACCEPTED, EnumSet.of(State.PREPARING, State.CANCELLED),            State.PREPARING, EnumSet.of(State.READY, State.CANCELLED),            State.READY, EnumSet.of(State.PICKED_UP),            State.PICKED_UP, EnumSet.of(State.DELIVERED),            State.DELIVERED, EnumSet.noneOf(State.class),            State.CANCELLED, EnumSet.noneOf(State.class));    static State current = State.PLACED;    // Mimics: UPDATE orders SET status = :to WHERE order_id = ? AND status IN (states that may move to :to)    static void apply(String source, State to) {        if (ALLOWED.get(current).contains(to)) {            System.out.printf("%-22s %-9s -> %-9s ok%n", source, current, to);            current = to;        } else {            System.out.printf("%-22s %-9s -> %-9s rejected%n", source, current, to);        }    }    public static void main(String[] args) {        apply("payment webhook", State.PAID);        apply("payment webhook (dup)", State.PAID);          // duplicate delivery        apply("restaurant tablet", State.ACCEPTED);        apply("restaurant tablet", State.PREPARING);        apply("customer app", State.CANCELLED);             // this policy allows it while preparing        apply("restaurant tablet", State.READY);            // arrives after the cancellation        apply("partner app", State.PICKED_UP);        System.out.println("final state: " + current);    }}

payment webhook        PLACED    -> PAID      okpayment webhook (dup)  PAID      -> PAID      rejectedrestaurant tablet      PAID      -> ACCEPTED  okrestaurant tablet      ACCEPTED  -> PREPARING okcustomer app           PREPARING -> CANCELLED okrestaurant tablet      CANCELLED -> READY     rejectedpartner app            CANCELLED -> PICKED_UP rejectedfinal state: CANCELLED

The duplicate webhook and the late "ready" tap change nothing. Whether a cancellation is allowed while the food is being prepared, and whether a fee applies, is a business rule; the state machine is where that rule is encoded, so it is enforced everywhere. In production, the transition table lives in the order service, each accepted transition writes an outbox event, and the rejected ones are logged and, where useful, answered with a clear message to the app ("order was cancelled").

An orchestrator in the order service drives each order (orchestration suits a long flow with many steps and compensations; Microsoft's Saga guidance compares it with choreography (Saga pattern)):

The pivot is the restaurant starting preparation: before it, cancellation is cheap and fully refundable; after it, food exists and policy decides who pays. Saga state is persisted in order_saga with a deadline_at; a scheduler (article 37) wakes the orchestrator when deadlines pass, so a crashed orchestrator instance or a silent restaurant never leaves an order stuck.

Assigning a partner the moment an order is placed wastes partner time (they wait at the restaurant for 20 minutes); assigning too late makes food wait. The dispatch service instead aims for the partner to arrive just as the food is ready:

ready_at  = accepted_at + predicted_prep_time (restaurant history, items, current load)travel    = predicted time for a candidate partner to reach the restaurantdispatch when: now + travel ~ ready_at - small buffer

• Candidates come from the same in-memory, cell-indexed location service as article 41.
• Offers and reservations use the same conditional updates on partner_assignment, so a partner never gets conflicting assignments.
• Batching: a partner can carry two orders from the same or nearby restaurants going in similar directions, if neither customer's ETA suffers beyond a threshold. Batching is an assignment optimisation run over a short window for each area.
• Predictions (preparation time, travel time) come from models trained on history; when predictions are poor, the system falls back to simpler rules and wider buffers.

• Once assigned, the partner's location is pushed to the customer's app over its connection, as in article 41.
• Status changes (accepted, preparing, picked up, arriving) go through the notification platform (article 33): in-app updates while the app is open, push notifications otherwise (for example via Firebase Cloud Messaging (FCM)).
• The restaurant tablet keeps a persistent connection for new orders, with a polling fallback and an automated call if a new order is not acknowledged.

• Per-city partitioning of order, dispatch and location services; each city scales independently.
• Autoscale ahead of the known daily peak, not only reactively.
• Restaurant throttling: restaurants can switch to "busy" (longer prep estimates, or temporarily closed), and the platform can automatically stop sending orders to a restaurant whose queue is growing.
• Demand shaping: delivery fees or longer ETAs in areas where partner supply is short; honest "high demand" messaging.
• Caching absorbs browsing spikes; checkout and order flows get priority over browsing when shedding load (article 23).

Customer app --> API gateway --> Discovery (cached read models, search) <-- catalogue events                             --> Order service (orders + saga + outbox, per city)                                    |-- Payment platform (article 39)                                    |-- Restaurant service --> tablet app (push, polling fallback, auto-call)                                    |-- Dispatch service (per city) <-- Location service (partners, article 41)                                    `-- Scheduler (saga deadlines)Order events (outbox --> stream) --> Notifications, tracking, analytics, earnings, ratings

• Order state: strongly consistent in the order service (single owner per order, conditional transitions).
• Cross-service state (payment, restaurant, dispatch): eventually consistent through the saga, with every intermediate state visible to the user.
• Menus and discovery: eventually consistent (a minute), re-validated at checkout.
• Partner assignment: strongly consistent per partner (reservation record).
• ETAs: predictions, continuously updated; presented honestly as estimates.

• Authorisation per party: customers see only their orders; restaurants only their orders and menu; partners only the deliveries assigned to them, and only for the duration needed.
• Privacy: customer address and phone are revealed to the partner only after assignment and hidden after delivery; phone numbers are masked through call proxying.
• Fraud: fake orders, refund abuse ("food never arrived"), promotion abuse, colluding partners; use delivery evidence (location trail, photo at doorstep where appropriate), account history and limits.
• Restaurant and partner payouts: changes to bank details require strong verification and are audited (article 28).
• Payments: tokens only, idempotent calls, verified webhooks (article 39).

"Food delivery coordinates three parties for every order. About 3 million orders a day means around 110 orders a second at the dinner peak, plus heavy but cacheable browsing and a 75,000-a-second partner location stream.

Discovery and menus are read models fed by catalogue events and cached per area; price and availability are re-checked at checkout. Checkout is idempotent and writes the order, its items with copied prices, saga state and an outbox event in one transaction. An orchestrator in the order service then drives an explicit state machine: payment through the payment platform, restaurant acceptance with a two-minute deadline and an automated call fallback, preparation, dispatch, pickup and delivery. Every transition is a conditional update on the current state, so duplicate and late events are harmless, and deadlines are enforced by the scheduler. Compensations cancel and refund automatically before preparation starts; after that, policy decides.

Dispatch reuses the ride-hailing location index and reservations, but times assignment so the partner arrives when the food is predicted to be ready, and batches nearby orders when ETAs allow. Customers see live tracking and push updates. Everything is partitioned by city, autoscaled ahead of dinner, and restaurants can be throttled when they fall behind."

• Next: Design an E-Commerce System: Catalog, Cart, Checkout, Inventory and Flash Sales, which has a similar order saga but very different inventory and traffic problems.
• Related: sagas (article 21), payments (article 39) and dispatch (article 41).