Design a Proximity Search System
like Yelp or Google Places

"Design Yelp" looks like a CRUD app with a map. It isn't. Beneath the surface are three distinct hard problems, and you need a credible answer to all three — not a deep dive into one.

Start with requirements before touching architecture. Every major design decision in this article traces back to a specific NFR target established here.

Functional requirements

Non-functional requirements

NFR reasoning

The load profile is extremely read-heavy. Searches dominate at ~1000× the review write rate. The implication: the architecture must optimise for read throughput and caching, not write throughput.

The architecture separates the read plane (geo-search, business detail, review listing — latency-critical, eventual consistency acceptable) from the write plane (review submission, business updates — correctness-critical, async propagation acceptable). A message queue connects them without coupling write latency to index update latency.

Component breakdown

CDN sits in front of all traffic and serves business detail pages, photo assets, and search result pages that have been explicitly cached. Static assets never hit origin servers.

API Gateway / Load Balancer terminates TLS, validates auth tokens, and routes requests to the correct downstream service fleet. Routes: /search → Search API, /businesses → Business API, /reviews → Review API.

Search API translates a geo+category+rating query into an Elasticsearch geo_distance query, checks the Redis result cache first, and applies the composite ranking score to the returned candidates before responding. It never touches the relational database on the hot path.

Business API handles CRUD for business profiles. Reads are served from read replicas behind a Redis cache for individual business detail pages. Writes go to the primary PostgreSQL node and trigger an Elasticsearch document upsert.

Review API accepts review submissions from authenticated users, writes to the Review DB (PostgreSQL), and publishes a review.created event to a durable message queue (Kafka). It does not recompute ratings synchronously — that happens downstream.

Elasticsearch (geo_point index) holds one document per business: geo-point coordinates, category, current Bayesian rating, review count, and hours. The Search API queries it exclusively for proximity searches. It is not the source of truth — it's a read-optimised projection of the Business DB, kept in sync by the Business API on write.

Redis Cache serves two distinct caches: (1) search result pages keyed by hash(lat, lon, radius, category, min_rating) with a 30-second TTL, and (2) per-business rating aggregates with a 60-second TTL.

Kafka (review events) decouples the Review API's write latency from the aggregate update latency. The Agg Worker consumes review.created events, recomputes the Bayesian rating for the affected business, writes to the review_aggregates table, and invalidates the Redis rating cache.

Agg Worker is a stateless Kafka consumer. It uses the outbox pattern: the Review API writes the event to an outbox table in the same PostgreSQL transaction as the review record, and Debezium publishes to Kafka from the WAL. This guarantees the event is never lost even if Kafka is temporarily unavailable during the write.

Architectural rationale

Real-world comparison

Before designing search, you must answer one foundational question: how do you represent a location in a way that makes "find all businesses within X km of me" fast? The answer isn't obvious — latitude and longitude are continuous, not naturally indexed. Three approaches dominate in production systems.

Our choice: Geohash at precision 6: each cell covers approximately 1.2 km × 0.6 km. For a 500 m search radius, we query the target cell plus its 8 neighbours (9 cells total) to handle edge-of-cell cases, then filter by exact Haversine distance in the application layer. This gives O(1) cell lookup via an Elasticsearch term query, with the distance filter applied to at most a few thousand candidates.

// Elasticsearch geo_distance query (used by Search API)
{
  "query": {
    "bool": {
      "filter": [
        {
          "geo_distance": {
            "distance": "500m",
            "location": { "lat": 37.7749, "lon": -122.4194 }
          }
        },
        { "term": { "category": "restaurant" } },
        { "range": { "bayesian_rating": { "gte": 4.0 } } }
      ]
    }
  },
  "sort": [
    { "_score": { "order": "desc" } },
    { "bayesian_rating": { "order": "desc" } }
  ],
  "size": 20
}

// Bayesian average formula (computed by Agg Worker, stored in ES)
// bayesian_rating = (C × global_mean + sum_ratings) / (C + review_count)
// C = 25 (prior count), global_mean = 3.8 (platform average)
// A new business with 0 reviews starts at 3.8 (the global mean)

Two endpoints dominate the hot path: the proximity search and the review submission. Both have non-obvious design choices.

GET /search/businesses

Use GET for search (not POST) because search results are cacheable by URL — CDN and intermediary proxies can serve cached results for identical queries. The query parameters form the cache key.

// Request
GET /search/businesses?lat=37.7749&lon=-122.4194&radius_m=500&category=restaurant&min_rating=4.0&page_token=eyJ...

// Response 200 OK
{
  "businesses": [
    {
      "business_id": "biz_8821",
      "name": "Mission Pie",
      "category": "restaurant",
      "distance_m": 312,
      "bayesian_rating": 4.6,
      "review_count": 843,
      "address": "2901 Mission St, San Francisco",
      "is_open_now": true,
      "thumbnail_url": "https://cdn.example.com/..."
    }
  ],
  "next_page_token": "eyJ...",
  "result_count": 47
}

POST /reviews

Use POST (not PUT) — review creation is not idempotent. Include an idempotency key header to prevent duplicate reviews on mobile retry.

// Request — Idempotency-Key header required
POST /reviews
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
  "business_id": "biz_8821",
  "rating": 5,
  "text": "Excellent pie. Highly recommended."
}

// Response 202 Accepted (async — rating will update within 60s)
{
  "review_id": "rev_449201",
  "status": "published",
  "rating_update_eta_s": 60
}

Optional endpoints by level

The search path is the hot path. It must complete in <200 ms p99, which means every component adds latency budget. The design enforces a strict cache-first strategy: Redis result cache → Elasticsearch → response. The database is never touched on the search hot path.

Data model decisions follow from access patterns — not from what's convenient to normalise. Here the dominant patterns are: proximity search (never touches relational DB), business detail fetch (single-row read, heavily cached), and review listing (paginated scan by business, sorted by time).

Access patterns

Two things stand out: the search path never touches the relational database, so the PostgreSQL schema only needs to serve detail pages and write operations. And the rating aggregate must be precomputed — it's read far too frequently to compute on demand.

The 1000:1 read:write ratio means caching is not optional — it's the primary scaling mechanism. Three distinct cache layers handle different parts of the read path, each with different TTL and invalidation strategies.

Cache invalidation

Each cache layer uses a different invalidation strategy, chosen based on the consistency requirement and the write frequency of the underlying data:

Three scalability problems surface at Yelp/Google Places scale that don't appear at smaller deployments: Elasticsearch shard hot spots, rating consistency under write bursts, and geographic read skew.

Three security concerns map directly to components already in the architecture: abuse prevention on the review write path, fraudulent business listing manipulation, and regulatory erasure requirements that span every storage tier. L6+ interviewers probe all three explicitly.

Review API rate limiting

Without rate limiting, a single malicious actor can submit thousands of fake reviews to manipulate ratings. The API Gateway enforces a per-user token-bucket rate limit on POST /reviews: maximum 1 review per business per user lifetime (enforced via the UNIQUE(user_id, business_id) constraint in the Review DB), plus a global velocity limit of 10 reviews per hour per user, enforced via a Redis counter (INCR ratelimit:review:{user_id}:{hour_bucket} with a 3600-second TTL). Requests exceeding the limit receive a 429 Too Many Requests response with a Retry-After header.

A separate, higher limit (100 requests/min) applies at the IP level to catch unauthenticated probing before authentication succeeds. This layered approach — IP-level → user-level → business-level — prevents both automated bots and coordinated human review campaigns.

Business listing fraud prevention

Fraudulent business listings — fake restaurants created to capture search traffic, or duplicate listings for SEO manipulation — degrade search quality. The Business API enforces three controls:

1. Geo-coordinate validation: Reject listings with coordinates in oceans, uninhabited areas, or outside the coverage zone. A simple land-boundary polygon check (pre-computed, ~50 KB dataset) catches the most obvious fakes.
2. Duplicate detection: Before creating a business, check for existing listings within 50 m with similar names (Levenshtein distance ≤ 3). Flag duplicates for manual review rather than auto-rejecting — legitimate businesses can share addresses (e.g., food courts).
3. Owner verification throttle: Limit unverified accounts to 3 business listings. Verified accounts (via phone, postal mail, or government ID) can create more. This prevents bulk listing spam without blocking legitimate multi-location businesses.

GDPR right-to-erasure pipeline

A user deletion request triggers a multi-stage erasure job implemented as a durable workflow (e.g., AWS Step Functions) to survive partial failures. The pipeline must reach every storage tier:

The interviewer calibrates depth to your level. Here's what good looks like at each, and what differentiates it from the level below.

Classic probes