Designing Yelp

1Understanding the Problem

Functional requirements — the features

These are the "users should be able to…" statements. The instructor limits scope to the three that matter, and pins down exactly what each means before moving on.

1. Search for businesses by name, location (lat/long), and category.
2. View a business and its reviews.
3. Leave a review on a business — a mandatory 1–5 star rating plus optional text.

Out of scope (below the line): admins adding/editing businesses, viewing businesses on a map, and personalized recommendations.

Scale — ask before you design

Before non-functional requirements, the instructor pins down scale by asking the interviewer. The agreed "Yelp-like scale" numbers are worth memorizing because every later trade-off leans on them:

Non-functional requirements — the qualities

These are the "-ilities" that make the system challenging. The trick is to name the unique ones, not generic ones — "everything should be low latency" is not interesting; identifying which operation is the latency risk is.

Availability over consistency (CAP)

Partition tolerance is a given, so the real choice is consistency vs. availability. The question to ask yourself: does every read need the very latest write? For Yelp, no.

Low-latency search (< 500 ms)

Search is the operation that is naturally high-latency if not optimized, so this is the requirement that actually shapes the design. Target: < 500 ms.

Scalability

The system must handle the 100M DAU / 10M businesses above. (Below the line: GDPR/data protection, fault tolerance, spam/abuse protection.)

The constraint

2Core Entities & the API

Core entities — the nouns

Start with a broad list of the primary entities (roughly the tables you'll persist and the data your API exchanges). Don't nail down every column yet — you'll have a clearer picture once you reach the high-level design.

• Business — the most important entity: name, location, category, average rating.
• Review — a rating (+ optional text) left by a user on a business.
• User — searches, views, and (when authenticated) leaves reviews.

The API — one endpoint per requirement

Walk the functional requirements one by one; each usually maps to an endpoint (sometimes two).

Search for businesses

// Search for businesses — GET because we're reading resources
GET /businesses?query&location&category&page  -> Business[]

View a business + its reviews

The simple version returns both at once:

GET /businesses/:businessId  -> Business & Review[]

Acceptable, especially at mid-level. But it's not optimal — reviews may be numerous (needs its own pagination) and slower to load than the core business details. Splitting into two endpoints lets the client load them in parallel and lazy-load reviews under a skeleton loader:

GET /businesses/:businessId          -> Business
GET /businesses/:businessId/reviews?page=  -> Review[]

Leave a review

// First POST endpoint — creates a new resource, nested under its business
POST /businesses/:businessId/reviews
{
  rating: number,   // 1–5, required
  text?: string     // optional
}

3High-Level Design

Goal of the high-level design: satisfy the functional requirements with the simplest architecture that works. Go endpoint by endpoint; layer depth later in the deep dives.

Two services behind one gateway, sharing a single database. Recreated from the source's high-level diagram.

3.1 · Satisfying each requirement

Search & view. The gateway forwards to the Business Service, which builds a query against the database. Both search and view are read-heavy and closely related, so they live in the same service. A naive search query looks like:

SELECT * FROM businesses
WHERE name LIKE '%coffee%'
  AND lat > ? AND lat < ? AND long > ? AND long < ?
  AND category = ?;

Leave a review. The Review Service writes to the database. The review model:

Review { id, userId, businessId (FK), rating 1–5, text? }

3.2 · One database, or one per service?

The justification for sharing here:

• Tiny data. ~1 TB fits comfortably on a single modern Postgres instance (which can handle 5–100+ TB) — no sharding needed.
• Tight coupling. Reviews and businesses are frequently joined; one database avoids cross-service joins.

The counter-argument — fault isolation (if the review DB dies, search shouldn't die with it) — is valid, but here it's mitigated with simple replication / read replicas rather than a full split.

4Deep Dive · Average Rating in Search Results

Search results show a partial business — name, hours, and crucially the average rating, which is the first thing users look at. Computing that average on the fly for every search would be brutal. The deep dive walks three solutions, from bad to great.

BadCompute on the fly

SELECT b.business_id, b.name, b.location, b.category,
       AVG(r.rating) AS average_rating
FROM businesses b
JOIN reviews r ON b.business_id = r.business_id
GROUP BY b.business_id;

Simple, no extra infra — but it re-runs an expensive JOIN + aggregate on every search, even when no new reviews arrived. A popular business can have hundreds of thousands of ratings to aggregate. At our scale this kills read performance. The fix: do the aggregation on write, not on read.

GoodPrecompute with a cron job

A periodic job (hourly/daily) computes each business's average and writes it to an average_rating column on the businesses table. Now search just reads the column.

GreatSynchronous update + concurrency control

Update the average as each review arrives. Add a num_reviews column so the new average is a cheap incremental formula (a few CPU cycles):

new_avg = (old_rating × num_reviews + new_rating) / (num_reviews + 1)

Wrap the "insert review + update business" in a single transaction (atomic — all or nothing). But two concurrent reviews can still clobber each other:

Two fixes, both fine:

• Pessimistic row lock — SELECT … FOR UPDATE the business row; the second transaction waits its turn. Ordering becomes strictly before/after.
• Optimistic concurrency control (OCC) — re-check num_reviews before writing; if it changed, someone else wrote, so retry. No lock contention; ideal when concurrency is low (as it is here).

-- pessimistic, in one transaction
BEGIN;
  lock business row (business_id);
  INSERT review;
  UPDATE num_reviews, average;
COMMIT;  -- lock released

5Deep Dive · One Review per User per Business

BadApplication-level check

def leave_review(user_id, business_id):
    reviews = db.get_reviews_for_business(business_id)
    if user_id in reviews:
        return "User has already reviewed this business"
    else:
        db.leave_review(user_id, business_id)

GreatEnforce it in the database

ALTER TABLE reviews
ADD CONSTRAINT unique_user_business UNIQUE (user_id, business_id);

Now a duplicate insert throws an error the app catches and returns to the client. Even the earlier race resolves cleanly: one writer wins, the second hits the unique-constraint error (as long as the data is on one instance — which it is).

6Deep Dive · Making Search Efficient

This is the crux of the interview — spend the most time here.

6.1 · Why the naive search is slow

// This query sucks. Very very slow.
SELECT * FROM businesses
WHERE latitude > 10 AND latitude < 20
  AND longitude > 10 AND longitude < 20
  AND name LIKE '%coffee%';

It forces a full table scan: the lat/long bounding box has no useful index, and LIKE '%coffee%' must inspect every row's name. Across 10M businesses that blows past the 500 ms budget.

BadJust add a B-tree on lat & long

CREATE INDEX idx_lat_long ON businesses (latitude, longitude);

Feels right, but a B-tree isn't built for 2-D data. Here's the instructor's diagram of why:

A B-tree can fetch each range, but each is a massive strip. You then intersect two huge strips to get the small target box — still very expensive at scale.

Three filters ⇒ three index types

6.2 · GreatElasticsearch

{
  "query": { "bool": { "must": [
    { "match": { "name": "coffee" } },
    { "geo_distance": { "distance": "10km",
        "location": { "lat": 40.7128, "lon": -74.0060 } } },
    { "term": { "category": "coffee shop" } }
  ]}}
}

That leaves two stores to keep in sync. Use Change Data Capture (CDC):

Every DB change is emitted as an event; a consumer replays it into Elasticsearch. Interviewers usually accept the single CDC arrow as an abstraction.

6.3 · GreatPostgres with extensions

A staff-level move: avoid a whole new technology (and the CDC sync problem) by using Postgres extensions that provide the same indexes in-place.

CREATE EXTENSION IF NOT EXISTS postgis;   -- geospatial: quadtrees, geohashes, R-trees
CREATE EXTENSION IF NOT EXISTS pg_trgm;   -- full-text search

PostGIS + pg_trgm + Postgres's built-in B-trees cover all three filters directly.

6.4 · Hand-rolling the geospatial index

(1) Pick and justify an index strategy. Usually weigh geohashing vs. quadtrees (R-trees if you know them). The instructor prefers quadtrees here: updates are infrequent and businesses cluster into dense regions like NYC.

(2) Second-pass filtering. The index returns a coarse square; you then filter in memory to the exact radius:

Stage 1: geospatial index → crude square. Stage 2: discard the corners outside the true circle using the Haversine formula (Pythagoras on a sphere).

(3) Sequence the filters to shrink the search space fastest. Distance is usually the most restrictive filter, so apply it first; then run name/category on the much smaller result set. (Sometimes name/category first is better — depends on the query; ask the interviewer.)

7Deep Dive · Searching by Location Name

The key realization: a city or neighborhood isn't a circle — it's an irregular polygon (a neighborhood like "The Mission" in SF, not just a zip or city). Everything built so far handles circles/radii, which is now insufficient. You need two pieces:

1. Location name → polygon. Add a locations table: name, type (city / neighborhood), and boundary (a list of lat/long points). Populate from public datasets like GeoJSON / Geoapify; index the name column.
2. Polygon → businesses inside it. Both Elasticsearch and PostGIS support this natively — geo_shapes (PostGIS) / geo_points & geo_bounding_box (Elasticsearch).

{ "query": { "geo_bounding_box": { "location": {
    "top_left":     { "lat": 42, "lon": -72 },
    "bottom_right": { "lat": 40, "lon": -74 }
}}}}

{
  "id": "123",
  "name": "Pizza Place",
  "location_names": ["bay_area", "san_francisco", "mission_district"],
  "category": "restaurant"
}

8What's Expected at Each Level

+A Note on Scaling

Pulling the scaling thread together (it recurs throughout the deep dives): 100M DAU is significant but not extreme. Standard moves apply — horizontally scale the stateless Business/Review services behind load balancers, add read replicas for the read-heavy load. Sharding isn't needed (real Yelp has far more data and would shard; our scoped version fits one instance — and saying so, with the math, is a "staff-y" move).

★Active Recall

Reconstruct the answers before expanding. If you can't, revisit the linked section.

↺Quick Revision