Files

71 lines
4.5 KiB
Markdown

# food-delivery
Companion code for the ankurm.com article **Low-Level Design: Food Delivery App (Zomato/Swiggy-Style) in Java**.
The core of an order-to-door system in plain Java: an order lifecycle as a state table, restaurant search with two rankings, bills in exact
paise, three rider-assignment strategies behind one interface, a dispatcher with a first-in-first-out waiting queue, atomic stock and kitchen
capacity, idempotent placing, and a seeded minute-by-minute simulation that compares the strategies on identical demand. Every figure and
console line in the article is quoted from a file in `output/`, which the JUnit tests write while asserting the same numbers. There is no
`docs/` folder: the explanations live in the article itself.
## Versions
| Component | Version | Verified against |
|---|---|---|
| JDK | Temurin 25.0.5.1+2 (LTS) | `java -version` |
| JUnit | 6.1.3 | `junit-bom` `maven-metadata.xml` on Maven Central (latest GA; 6.2.0-M1 is a milestone) |
| Maven | 3.9.11 | `mvn -version` |
| maven-surefire-plugin | 3.6.1 | `maven-metadata.xml` on Maven Central (latest GA) |
No frameworks and no runtime dependencies: everything in `src/main` is plain Java.
## Quickstart
```bash
cd food-delivery
export JAVA_HOME=/path/to/jdk-25 PATH="$JAVA_HOME/bin:$PATH"
./scripts/run-all.sh # runs every test and regenerates output/*.txt
```
The first Maven run must be online so the plugins land in the local cache. Three transcripts contain figures that depend on thread timing
(`09-stock-race.txt`, `10-partner-claim.txt`, `11b-reject-vs-cancel.txt`); they say so in their first lines and can differ from run to run.
Every other transcript is identical on every run.
## The pieces
| Class | Role |
|---|---|
| `OrderStatus` | the whole lifecycle as one table: eight legal moves out of sixty-four |
| `Order` | the only place a status changes; every mutator is synchronized, so a race on one order has one winner |
| `FoodDeliveryService` | the facade: search, place, accept, reject, prepare, ready, pick up, deliver, cancel |
| `Restaurant` | menu, rating, location and a kitchen capacity taken with a compare-and-set loop |
| `DeliveryPartner` | a rider whose claim is one `compareAndSet(AVAILABLE, BUSY)` |
| `PartnerAssignmentStrategy` | picks one rider from a list; `NearestPartner`, `RatedWithinRadius`, `LongestIdle` |
| `Dispatcher` | matches accepted orders to riders; orders with no rider wait in a FIFO queue |
| `StockLedger`, `Inventory` | all-or-nothing reservation of limited portions under one lock per restaurant |
| `PricingPolicy`, `StandardPricing` | subtotal, distance fee, free-delivery threshold, 5% tax rounded half up |
| `RestaurantRanking` | `NEAREST` and `TOP_RATED`, both ending in the id so ties never swap |
| `OrderListener`, `OrderEvent` | Observer: every status change and rider assignment is published |
| `Simulation` | seeded city and demand; runs a strategy to the last delivery |
| `FoodDeliveryException` | sealed family of business-rule failures |
The tests also hold two deliberately wrong versions, `NaiveInventory` and a naive rider claim, so the failures can be reproduced.
## Transcripts
| File | Written by | What it shows |
|---|---|---|
| `01-happy-path.txt` | `LifecycleTest` | one order from placed to delivered: bill, rider, event log |
| `02-state-machine.txt`, `02b-illegal-moves.txt`, `02c-no-partner.txt` | `StateMachineTest` | the 8x8 table, exact messages for illegal moves, pick-up without a rider |
| `03-pricing.txt` | `PricingTest` | delivery fee by distance, free delivery, half-up tax |
| `04-validation.txt` | `ValidationTest` | ten bad requests with exact messages, stock untouched |
| `05-search.txt` | `SearchTest` | the same restaurants ranked two ways |
| `06-assignment.txt`, `06b-radius-fallback.txt` | `AssignmentTest` | one order, three strategies, three riders |
| `07-dispatch-queue.txt`, `07b-cancel-while-waiting.txt` | `DispatchQueueTest` | the waiting queue and what frees it |
| `08-cancel-reject.txt` | `CancelRejectTest` | stock, kitchen slot and rider all come back |
| `09-stock-race.txt` | `StockRaceTest` | 16 buyers, 10 portions: naive versus locked |
| `10-partner-claim.txt`, `10b-dispatch-under-load.txt` | `PartnerClaimTest` | naive versus compare-and-set; 200 orders, 20 riders, 8 threads |
| `11-accept-capacity.txt`, `11b-reject-vs-cancel.txt` | `AcceptRaceTest` | capacity holds; reject versus cancel has one winner |
| `12-idempotency.txt` | `IdempotencyTest` | a double tap and 16 racing retries create one order |
| `13-simulation.txt` | `SimulationTest` | three strategies at three load levels on identical orders |