A repeatable approach

You've now seen every part of Part 1 one at a time: APIs, data models, caches, more servers, replicas, live updates, queues, rate limits and growth. Real design work doesn't arrive one topic at a time. It arrives as a blank page and a sentence like "design a ratings feature" or "design a ride-hailing app".

This lesson gives you a fixed order of steps to follow every time. Not because design is a checklist, but because a fixed order stops you skipping the parts that matter and lets you spend your thinking on the problem instead of on "what do I do next?"

The six steps

Each step feeds the next. The numbers come from the requirements. The API comes from the functional requirements. The data model comes from the API. The design comes from the data and the numbers. If you jump straight to step 5, you're drawing boxes with nothing underneath them.

To make it concrete, we'll run all six on a small Tiffin feature: ratings and reviews. After each delivery, a customer can rate the restaurant from 1 to 5 stars and leave a short review. The restaurant page shows its average rating and recent reviews.

Step 1: Requirements

Start by asking, not assuming. Who uses this, and what do they need?

Functional:

• A customer can rate a delivered order once, 1 to 5 stars, with an optional text review.
• The restaurant page shows the average rating, the number of ratings and the 20 most recent reviews.
• Restaurants can see their reviews in the kitchen tablet app.

Non-functional:

• The restaurant page loads in under 200 ms at p99, since it's viewed constantly.
• A new rating shows up in the average within a few minutes. It doesn't need to be instant.
• One rating per order, even if the app retries the request.

Also say what's out of scope: replies from restaurants, photos and fake-review detection. Naming them shows you thought about them, and keeps the design small.

Step 2: Numbers

Use what you know. Tiffin does 250,000 orders a day. Say 30% of customers rate their order.

Ratings written:  250,000 x 30% = 75,000 a day ≈ 1 a second on average, ~4 at dinner peak
Restaurant page views: say 10 per order placed = 2.5 million a day ≈ 30/s avg, ~140/s at peak
Storage: 75,000 x ~500 bytes = ~37 MB a day ≈ 14 GB a year

Two things fall out of this. Reads outnumber writes about 30 to 1. And the data is small. So this feature is about fast reads of the average, not about storage or write load.

Step 3: API

Two or three endpoints cover it:

POST /orders/{orderId}/rating
  body: { "stars": 4, "text": "Great biryani, a bit late" }
  201 Created, or 409 Conflict if this order is already rated

GET /restaurants/{id}/ratings/summary
  200 { "average": 4.3, "count": 18234 }

GET /restaurants/{id}/reviews?cursor=...&limit=20
  200 { "reviews": [...], "next_cursor": "..." }

Notice the decisions hiding here: the rating hangs off the order, so the server can check that the order belongs to this customer and was delivered ("only customers who ordered can rate"), the 409 handles retries, and reviews use cursor pagination from Module 2.

Step 4: Data

CREATE TABLE ratings (
  order_id      bigint PRIMARY KEY,   -- one rating per order, enforced by the database
  restaurant_id bigint NOT NULL,
  customer_id   bigint NOT NULL,
  stars         smallint NOT NULL CHECK (stars BETWEEN 1 AND 5),
  review_text   text,
  created_at    timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ratings_restaurant_recent ON ratings (restaurant_id, created_at DESC);

CREATE TABLE restaurant_rating_summary (
  restaurant_id bigint PRIMARY KEY,
  rating_sum    bigint NOT NULL,
  rating_count  integer NOT NULL
);

The main queries are: insert a rating, read 20 recent reviews for a restaurant (served by the index), and read the summary. The summary table exists because computing AVG(stars) over 18,000 rows on every page view, over 100 times a second, is wasteful when the answer changes once every few minutes.

Step 5: High-level design

%% caption: Ratings feature. Every box traces to a requirement or a number from steps 1 and 2.
flowchart TD
  CA([Customer app]) -- "rate an order" --> S[Server]
  RP([Restaurant page]) -- "read the summary" --> S
  S -- "rating and its job, one transaction" --> PG[("Postgres<br/>ratings, summary, jobs")]:::store
  PG -- "jobs table" --> W["Worker<br/>updates summary"]
  W --> PG
  S --> C[("Cache<br/>summary, 5 min TTL")]:::hot

Walk through it, tying each part to a reason:

• Postgres stores ratings, because the primary key enforces one rating per order.
• The jobs table and worker update the summary in the background, because "within a few minutes" allows it (Module 7). The job is inserted in the same transaction as the rating, so a rating can never be saved without its job, or the other way round.
• The cache serves the summary, because reads outnumber writes 30 to 1 and the page must load in 200 ms (Module 3).

No new database, no search engine, no service. The numbers didn't ask for them.

Step 6: Deep dive

Pick the part most likely to go wrong. Here, it's keeping the summary correct.

The worker adds the new rating to rating_sum and increments rating_count. But the queue delivers at least once, so the same job can run twice and count a rating twice (Module 7). The fix: in one transaction, mark the rating as counted and update the summary only if it wasn't already.

BEGIN;
UPDATE ratings SET counted = true WHERE order_id = $1 AND counted = false;
-- only if that updated 1 row (otherwise this job already ran):
INSERT INTO restaurant_rating_summary (restaurant_id, rating_sum, rating_count)
  VALUES ($3, $2, 1)
  ON CONFLICT (restaurant_id) DO UPDATE
  SET rating_sum = restaurant_rating_summary.rating_sum + $2,
      rating_count = restaurant_rating_summary.rating_count + 1;
COMMIT;

The insert-or-update matters for a restaurant's very first rating: a plain UPDATE would match no summary row and silently drop it.

That needs a counted boolean NOT NULL DEFAULT false column on ratings, which is a nice example of the loop from Module 1: the deep dive sent us back to step 4.

Then ask the failure questions. What if the worker is down for an hour? The summary is an hour stale, which is acceptable, and it catches up from the queue. What if the summary drifts because of a bug? A nightly job recomputes it from ratings, the source of truth.

Spend your time where it matters

In a 45-minute design discussion, a rough budget:

The deep dive gets the most time because it's where real design happens. Everyone can draw a server and a database. Not everyone can explain what happens when a job runs twice.

Be flexible about the order inside a session. If the hard part is obvious from the start (live location for a ride-hailing app, say), mention it early and come back to it. The steps are a spine, not a cage.