Online Food Delivery
Service boundaries, interactions, and API contracts - design the seams of a small service-based system.
intermediate3-4 hours
What you will produce
- Service responsibility map
- Order-flow interaction outline
- Component sketch
- API specification
Your client runs a regional food-delivery platform. Customers browse menus and place orders, restaurants confirm and cook, couriers pick up and deliver, and all three parties watch the order status change live. The current system is one codebase maintained by three teams who keep stepping on each other, so the engineering lead has decided to move to a small set of services. Your assignment is not to build anything yet - it is to design the seams: which services exist, what each one owns, how they talk to each other, and what their APIs promise.
This is a different exercise from modeling a single class hierarchy. The units are coarser, the interesting decisions are about boundaries and contracts rather than inheritance, and every arrow you draw between two services is a network call that can fail. You will practice partitioning a domain by business capability, tracing one end-to-end flow through the services, sketching dependencies, and writing the API contract for the order lifecycle.
Before you start
You should be comfortable with:
- Microservices trade-offs - what splitting into services buys you and what it costs. This project applies that reasoning to a concrete domain.
- REST resource design - resources, methods, and status codes.
- Dependency - the dashed arrow you will use for the component sketch.
- Information Expert - the same assign-responsibility-to-the-data-owner reasoning, applied at service scale.
Open DiaGO Studio's component editor for Step 3. Everything else in this project is produced as text or tables, so also have a plain text editor or paper ready.
Step 1: Identify services and responsibilities
Work on paper or in a text file. List the four services - OrderService, RestaurantService, CourierService, NotificationService - and for each one write what it is responsible for, what data it owns, and what it is explicitly not responsible for. The "not responsible for" column is where boundary thinking actually happens: a responsibility that two services could plausibly claim is a boundary you have not decided yet.
Draw boundaries by business capability, not by technical layer. "Everything about orders" is a capability; "the database layer" is not. Capability-aligned services can change and deploy independently because a change to menu rules rarely touches order rules. That independence is the payoff of a service split - and it comes with real costs in network failures and eventual consistency, which is why the trade-offs are worth rereading before you commit.
| Service | Responsible for | Owns data | Not responsible for |
|---|---|---|---|
| OrderService | Order lifecycle: creation, validation, status transitions, pricing totals | Orders, order items, status history | Menu contents, courier locations, sending emails |
| RestaurantService | Menus, availability, accepting or rejecting incoming orders | Restaurants, menus, opening hours | Order pricing, delivery logistics |
| CourierService | ... | ... | ... |
| NotificationService | ... | ... | ... |
Hint: when a responsibility could go either way, ask which service would have to change if the related business rule changed. Courier pay rates changing should never force a redeploy of OrderService.
Step 2: Model the order flow
Trace one order end to end: place order -> restaurant accepts -> courier assigned -> delivered. For each interaction, write who calls whom, whether the call is synchronous (the caller waits for the answer) or asynchronous (an event, handled later), and what happens when it fails.
Use this format, and complete the flow through delivery:
1. Customer -> OrderService: POST /orders (sync)
Failure: restaurant closed or item unavailable -> 422, no order created.
2. OrderService -> RestaurantService: OrderPlaced event (async)
Failure: RestaurantService is down -> event stays queued and is
retried; the order remains in PLACED and the customer sees that.
3. Restaurant staff -> RestaurantService -> OrderService: accept order (sync)
Failure: ...
4. ...The failure lines are the point of the exercise. A flow where every step silently succeeds is fiction; a flow where each step states its failure behavior is a design.
Step 3: Sketch the components and their dependencies
Open the component editor. Create one component per service, give each its provided and required interfaces, and connect them with dependency and assembly connectors pointing from caller to callee. Label a connector with the nature of the call where it helps: sync for request/response, async for events. See the Smart Library components example for a worked layout.
Two things to check as you draw:
- Direction. A dependency arrow from OrderService to RestaurantService means order code knows restaurant endpoints exist. Every arrow you add is coupling; every cycle is a smell.
- NotificationService should have no incoming synchronous arrows on the critical path. Placing an order must not fail because the email provider is down. Model notifications as async events flowing into NotificationService - the same inversion the Observer pattern applies between objects.
Step 4: Design the API endpoints
Design OrderService's public API for the order lifecycle. Start from REST resource design: identify the resources, then map lifecycle actions onto methods and paths. On paper or in a text file, build a table like this and complete it - you still need courier assignment, order retrieval for tracking, and cancellation:
| Method | Path | Purpose |
|---|---|---|
| POST | /orders | Place a new order |
| GET | /orders/{id} | Fetch one order with current status |
| POST | /orders/{id}/acceptance | Restaurant accepts the order (creates an acceptance) |
Accept and assign are the interesting rows because they are not CRUD: they are state transitions with their own rules and data (who accepted, which courier, when). Modeling the transition as a sub-resource - POST /orders/{id}/acceptance rather than a bare status PATCH - gives the transition a natural place for its request body and its own failure responses. This is a widely used convention, not a REST law; a PATCH-based design can also be defended if its validation rules are explicit.
Step 5: Define request and response schemas
Write concrete JSON for the three core shapes. First, the POST /orders request:
{
"restaurantId": "rest_982",
"items": [
{ "menuItemId": "mi_301", "quantity": 2 },
{ "menuItemId": "mi_305", "quantity": 1 }
],
"deliveryAddress": {
"street": "14 Hill Road",
"city": "Pune",
"postcode": "411001"
}
}The 201 Created response - note it returns the full resource, including server-owned fields the client must not send:
{
"id": "ord_57210",
"status": "PLACED",
"restaurantId": "rest_982",
"items": [
{ "menuItemId": "mi_301", "quantity": 2, "unitPrice": 240 },
{ "menuItemId": "mi_305", "quantity": 1, "unitPrice": 180 }
],
"totalAmount": 660,
"placedAt": "2026-07-10T12:41:03Z"
}Every error, from any endpoint, uses one envelope. Here it is carrying a 422 Unprocessable Entity validation failure:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "The order could not be created.",
"details": [
{ "field": "items", "issue": "must contain at least one item" },
{ "field": "deliveryAddress.postcode", "issue": "is required" }
]
}
}Using 422 for well-formed-but-invalid requests (versus 400 for malformed ones) is a common industry convention, not a formal requirement - pick one interpretation and apply it consistently. Now write the schemas for the acceptance and assignment endpoints yourself, including at least one failure body each (what does rejecting an already-accepted order return?).
Step 6: Explain the service boundaries
Finally, write a short justification - a paragraph per service - answering: why these four? Each service should map to a capability with its own vocabulary, its own reasons to change, and its own data. State explicitly what data each service owns, because ownership is the rule that makes the split work: no shared database. Each service is the only writer of its tables; everyone else gets that data through its API or its events. If two of your services need to write the same table, your boundary is wrong - merge them or move the data.
Also name what would change your mind, because boundaries are decisions, not truths:
Reach for it
- The two capabilities change for different business reasons
- Separate teams own them and want to deploy independently
- One capability has a very different load or availability profile
Avoid it
- A single business transaction would have to span both services
- Every request would need a synchronous chain through both
- One small team owns everything and gains nothing from the split
Check your work
- Does every endpoint in your API table document a success response and at least one failure response?
- Does every cross-service call in your order flow state what happens when the callee is down or says no?
- Can you name the one business capability each service owns, in one sentence, without the word "and"?
- Is each piece of data written by exactly one service?
- Are the accept and assign transitions modeled deliberately (sub-resource or justified PATCH), rather than as untyped status updates?
- Does NotificationService receive events asynchronously, with no synchronous arrow into it on the order-placing path?
- If RestaurantService is completely down, can a customer still view the status of an order they placed yesterday?
Going further
- Idempotency. A customer's app times out on
POST /ordersand retries. Design an idempotency-key mechanism so the retry cannot create a second order, and specify which status code the duplicate attempt returns. - Live courier tracking. Couriers report their location every few seconds. Decide whether customers poll or the platform pushes, and extend your interaction outline with the event flow - the Observer pattern reasoning scales up here.
- Cancellation saga. A customer cancels after a courier is assigned. Walk the compensating actions across all four services and define the point of no return after which cancellation becomes a refund request instead.
Practice
Take your Step 2 outline and inject a failure at step 3: the restaurant's tablet is offline and the order is never accepted or rejected. Design the timeout policy - how long OrderService waits, what status the order moves to, which services are told, and what the customer sees - and add the new transitions to both your interaction outline and your API table.