Design Yelp

1. Search Businesses

Users search for businesses by text query and location. Results are filtered by criteria (open now, price range, categories) and sorted by distance, rating, or relevance.

A user searches "pizza" while standing in Manhattan. The system must find pizzerias within 2km, filter to those currently open, and rank by distance and rating. Let's build this incrementally.

The Problem

The naive approach queries the Business Database directly:

At 200M businesses, this query scans millions of rows. The distance calculation runs for every row. The ILIKE '%pizza%' can't use a B-tree index. Response time: 2-3 seconds. At 5,800 peak QPS, the database melts.

Step 1: Add a Search Index

Move geo+text queries to a dedicated search index like Elasticsearch. The Search Service sits between the API Gateway and the index.

Elasticsearch provides geo queries (geohash-based spatial filtering), text search (inverted indexes for fast keyword matching), and combined queries (efficient intersection of geo + text + filters). Search now returns in 50ms.

But there's a problem. A restaurant updated their hours yesterday. The database shows "closes at 10pm" but the search index still shows "closes at 9pm." A user filters for "open now" at 9:30pm and the restaurant doesn't appear. The index is stale.

Step 2: Keep the Index Fresh with CDC

The Search Index must stay in sync with the Business Database. We could update both on every write, but that couples the write path to index availability—if Elasticsearch is slow, business updates fail.

Instead, use Change Data Capture (CDC). A CDC pipeline (Debezium, DynamoDB Streams, etc.) watches the Business Database transaction log and pushes changes to the Search Index asynchronously. Business updates succeed immediately; the index catches up within seconds.

Now the architecture is complete: fast searches via the index, fresh data via CDC, and the database remains the source of truth.

2. View Business Details

Users view a business page showing details (name, hours, photos), aggregate rating (4.5 stars from 234 reviews), and paginated reviews.

A user taps a search result to view Joe's Pizza. The page needs the business name, hours, photos, the aggregate rating (4.5 stars from 234 reviews), and the first page of reviews. Let's build this incrementally.

The Problem

The naive approach joins everything in one query:

This calculates the average from all 234 reviews on every page load. A popular restaurant with 5,000 reviews makes this query slow. At 1,700 page views per second, the database struggles.

Step 1: Separate Business and Review Queries

Business metadata (name, hours, location) and reviews have different access patterns. Business data rarely changes and can be cached aggressively. Reviews are append-mostly and need pagination.

Split into two services: Business Service for metadata, Review Service for paginated reviews. The API Gateway fans out to both.

Now business data comes from cache (fast), and reviews are paginated (only fetch 10 at a time). But we still calculate AVG(stars) on every request. A restaurant with 5,000 reviews still requires scanning all of them.

Step 2: Precompute Rating Aggregates

Instead of calculating AVG(stars) on read, store rating_avg and rating_count in the Business table or a dedicated cache. Update these values asynchronously when reviews change.

Trade-off: The aggregate might be seconds behind the actual reviews (eventual consistency). A user submits a 5-star review; the page still shows 4.5 stars for a few seconds. This is acceptable—users don't expect real-time aggregate updates.

Now the business page loads three independent pieces: cached business metadata, precomputed aggregates, and the first page of reviews. Each scales independently.

3. Write a Review

Users write reviews with a star rating, text, and optional photos. The review must be durable, and derived data (aggregates, search index) must eventually update.

A user finishes dinner and writes a 4-star review with a photo. The system must save the review durably, then update derived data: the rating aggregate and search index signals. Let's build this incrementally.

The Problem

When a user submits a review, the system needs to:

1. Save the review to the database
2. Update the business's rating_avg and rating_count
3. Update search index signals (businesses with more/better reviews rank higher)

The naive approach does all three synchronously. User clicks submit → write review → update aggregates → update search index → return success. If Elasticsearch is slow, the user waits. If Elasticsearch is down, the review fails even though it could have been saved.

Step 1: Write to Database First, Return Success

The user cares that their review is saved. They don't care if the aggregate updates immediately. So: write the review to the Review Database, commit, then return success.

Now writes are fast (tens of ms). But the derived data (aggregates, search index) is stale. The user submitted a 5-star review, but the business page still shows the old average.

Step 2: Async Fanout via Message Queue

After writing the review, publish a review_created event to a message queue (Kafka, SQS, etc.). Workers consume events and update:

• Rating aggregates: update rating_sum and rating_count (avg = sum/count)
• Search index signals: update review_count and rating for the business

This decouples the write path from derived data updates. If Elasticsearch is down, reviews still save. Workers retry when it recovers. Even at low write QPS, the queue is mainly for decoupling fanout and handling downstream outages, not raw throughput.

The review row exists in the primary database immediately. But if the business page reads reviews from a replica or cache, replication lag or cached pages can hide the new review for a few seconds.

Step 3: Read-Your-Writes for the Author

The author should see their review immediately. Two options:

1. Read from primary: For the author's session, read reviews from the primary database instead of a replica
2. Optimistic display: Include the new review in the API response and have the client display it locally

Other users see the review with a slight delay (seconds) as replicas sync and caches invalidate. This is acceptable.

Photo Uploads

If photos are in scope, they follow a separate path:

1. Client uploads photo to object storage (S3) via presigned URL
2. Client includes the photo URL in the review submission
3. Photos are served via CDN for fast loading

When a user searches "pizza," they expect the best nearby pizzerias—not just the closest ones. Let's compare ranking approaches.

The Challenge

Search results need to balance multiple signals: proximity (users want nearby options), quality (high ratings matter), and confidence (a 4.5-star rating from 500 reviews is more trustworthy than a 5-star from 1 review). At 50K QPS with 200M businesses, ranking must also be fast.

Approach 1: Distance-Only Ranking

Sort results by distance from the user. Simple and fast.

Limitation: The closest pizza place might have 2 stars and reviews mentioning "cold pizza." Users expect quality, not just proximity.

Approach 2: Rating × Distance

Combine signals: score = rating × (1 / distance). Higher-rated places rank above closer mediocre ones.

Limitation: A new restaurant with one 5-star review (from the owner's friend) outranks an established 4.5-star place with 500 genuine reviews. Raw ratings don't account for confidence.

Approach 3: Smoothed Ratings

Apply Bayesian smoothing: businesses with few reviews get pulled toward the global average. Formula: smoothed = (sum_of_stars + prior × avg) / (num_reviews + prior). With prior = 10, a single 5-star becomes ~3.8 stars. An established 4.5 with 500 reviews stays at 4.5.

Limitation: At 50K QPS, scoring millions of businesses with complex formulas is too slow.

Approach 4: Two-Stage Retrieval

Split ranking into stages:

1. Retrieval: Search index returns top 1000 candidates using simple scoring (text match + geo filter). Fast—uses precomputed index structures.

2. Reranking: A lightweight service rescores 1000 candidates with richer signals (smoothed rating, review freshness, category match). Returns top 20.

This is fast (only 1000 candidates scored) and accurate (rich signals in reranking).

Recommendation

Use two-stage retrieval with smoothed ratings in the reranking stage. Start with search engine scoring (Elasticsearch function_score). Add application-level reranking when you need ML models or A/B testing flexibility.