Design Yelp: Location-Based Business Discovery Platform

A comprehensive system design for a location-based business discovery service. This design addresses proximity search at scale, multi-signal ranking, and user-generated content moderation with a focus on sub-100ms search latency and global availability.

Abstract

Proximity services solve a fundamentally different problem than traditional text search: the answer depends not just on what you’re looking for but where you are. This creates unique indexing challenges—you can’t pre-compute rankings when the query center point changes with every request.

The core trade-off space:

• Indexing strategy: Geohash (simple, bounded precision) vs. Quadtree (adaptive density) vs. R-tree (optimal for rectangles). Each trades query flexibility against write complexity and memory overhead.
• Search radius handling: Fixed grid cells leak results at boundaries; hierarchical approaches add latency but guarantee coverage.
• Ranking signals: Distance alone produces poor results. Real systems blend distance, ratings, recency, personalization, and business attributes—but more signals mean slower ranking and harder explainability.
• Write path complexity: Business data changes infrequently, but reviews flow continuously. Decoupling these paths enables independent scaling but introduces consistency windows.

Real-world context: Yelp handles 178 million unique visitors monthly with 244 million reviews. Google Maps indexes 200+ million places. Foursquare’s Pilgrim SDK processes 14 billion location signals daily for venue detection. These systems demonstrate that sub-100ms latency is achievable at scale, but requires aggressive caching, denormalization, and carefully bounded search spaces.

Mental model: Think of this as three systems in one: (1) a geospatial index that answers “what’s nearby?”, (2) a ranking engine that orders results by relevance, and (3) a content platform that manages reviews, photos, and business data. The challenge is making them work together with consistent latency under varying load patterns.

Requirements

Functional Requirements

Scope for this article: We’ll design the core proximity search, business data, and review systems. Check-ins and advanced personalization are covered briefly; advertising and business analytics are out of scope.

Non-Functional Requirements

Scale Estimation

Users:

• Monthly Active Users (MAU): 100M
• Daily Active Users (DAU): 30M
• Peak concurrent users: 3M (10% of DAU)

Businesses:

• Total businesses: 10M globally
• Active businesses (updated in last year): 5M
• New businesses per day: 10K

Traffic:

• Search queries: 30M DAU × 5 searches/day = 150M searches/day ≈ 1,700 QPS
• Peak search: 3× average = 5,100 QPS
• Business profile views: 30M DAU × 10 views/day = 300M/day ≈ 3,500 QPS
• Review writes: 30M DAU × 0.01 reviews/day = 300K reviews/day ≈ 3.5 writes/sec
• Photo uploads: ~100K/day

Storage:

• Business data: 10M × 10KB = 100GB
• Reviews: 200M reviews × 2KB = 400GB
• Photos: 500M photos × 500KB average = 250TB (object storage)
• Search index: ~50GB (denormalized business + location data)
• 5-year projection: ~2PB total (dominated by photos)

Design Paths

Path A: Geohash-Based Indexing

Best when:

• Uniform business density across regions
• Fixed search radius (e.g., always 5km)
• Simpler operational requirements

Architecture:

Key characteristics:

• Geohash encodes lat/lon into a string where prefix matches indicate proximity
• 6-character geohash ≈ 1.2km × 600m cell; 5-character ≈ 5km × 5km
• Query requires checking target cell + 8 neighboring cells to handle boundary cases
• Index structure is a simple key-value map: geohash → list of business IDs

Trade-offs:

• ✅ Simple to implement and debug
• ✅ Excellent cache locality (nearby queries hit same cells)
• ✅ Easy sharding by geohash prefix
• ❌ Fixed precision creates density mismatches (Manhattan vs. rural Wyoming)
• ❌ Variable radius searches require multiple precision levels
• ❌ Edge cases at cell boundaries require neighbor expansion

Real-world example: Uber’s geospatial indexing uses geohash for initial filtering, then refines with exact distance calculations. Their H3 system (hexagonal hierarchical index) evolved from geohash limitations but shares the prefix-based lookup principle.

Path B: Quadtree / S2 Geometry

Best when:

• Highly variable business density
• Need for adaptive precision
• Complex geometric queries (polygons, routes)

Architecture:

Key characteristics:

• Recursively subdivides space until each cell contains ≤ N businesses
• Dense areas (cities) have deeper trees; sparse areas (rural) stay shallow
• Google’s S2 Geometry library uses this with spherical projection
• Cell IDs encode the path from root, enabling range queries

Trade-offs:

• ✅ Adapts to density automatically
• ✅ Efficient for variable-radius queries
• ✅ Handles complex shapes (polygons, paths)
• ❌ More complex implementation
• ❌ Tree rebalancing on updates
• ❌ Harder to cache (cells have variable sizes)

Real-world example: Google Maps uses S2 cells extensively. A search in Manhattan might use level-16 cells (~150m), while rural areas use level-10 (~10km). Foursquare’s Pilgrim SDK uses S2 for geofencing with 14 billion daily signals.

Path C: R-tree (Elasticsearch/PostGIS)

Best when:

• Need full-text search combined with geo
• Complex attribute filtering
• Leveraging existing search infrastructure

Architecture:

Key characteristics:

• Elasticsearch uses BKD trees (variant of R-trees) for geo_point fields
• Combines spatial queries with full-text search and filtering
• geo_distance query returns all points within radius
• geo_bounding_box for rectangular regions

Trade-offs:

• ✅ Combines geo + text + attributes in single query
• ✅ Mature tooling, operational knowledge
• ✅ Built-in relevance scoring
• ❌ Higher latency than specialized geo indexes (~20-50ms vs ~5ms)
• ❌ Memory overhead for inverted indexes
• ❌ Write amplification for index updates

Real-world example: Yelp uses Elasticsearch for their search infrastructure. Their architecture handles 150M+ searches per day with sub-100ms latency by combining aggressive caching with optimized ES configurations.

Path Comparison

This Article’s Focus

This article focuses on Path C (Elasticsearch-based) because:

1. Most proximity services need combined text + geo + attribute search
2. Elasticsearch is widely deployed with known operational patterns
3. The latency difference (~30ms vs ~5ms) is acceptable when total budget is 100ms
4. Avoiding a separate geo-index reduces system complexity

For systems requiring sub-10ms geo queries at massive scale (e.g., ride-sharing dispatch), Path B with custom S2 implementation would be more appropriate.

API Design

Search Nearby Businesses

Endpoint: GET /api/v1/businesses/search

Query Parameters:

Response (200 OK):

1
{
2
  "businesses": [
3
    {
4
      "id": "biz_abc123",
5
      "name": "Joe's Coffee",
6
      "slug": "joes-coffee-san-francisco",
7
      "location": {
8
        "lat": 37.7749,
9
        "lon": -122.4194,
10
        "address": "123 Market St",
11
        "city": "San Francisco",
12
        "state": "CA",
13
        "postal_code": "94102",
14
        "country": "US"
15
      },
16
      "distance_meters": 450,
17
      "categories": [{ "id": "coffee", "name": "Coffee & Tea" }],
18
      "rating": 4.5,
19
      "review_count": 1247,
20
      "price_level": 2,
21
      "hours": {
22
        "is_open_now": true,
23
        "today": "7:00 AM - 8:00 PM"
24
      },
25
      "photos": {
26
        "thumbnail": "https://cdn.example.com/photos/abc123/thumb.jpg",
27
        "count": 523
28
      },
29
      "attributes": {
30
        "wifi": true,
31
        "outdoor_seating": true,
32
        "takes_reservations": false
33
      }
34
    }
35
  ],
36
  "total": 847,
37
  "cursor": "eyJvZmZzZXQiOjIwfQ==",
38
  "search_metadata": {
39
    "center": { "lat": 37.7749, "lon": -122.4194 },
40
    "radius_meters": 5000,
41
    "query_time_ms": 42
42
  }
43
}

Error Responses:

• 400 Bad Request: Invalid coordinates, radius out of range
• 429 Too Many Requests: Rate limit exceeded

Rate Limits: 100 requests/minute per user (authenticated), 20/minute (anonymous)

Get Business Details

Endpoint: GET /api/v1/businesses/{business_id}

Response (200 OK):

1
{
2
  "id": "biz_abc123",
3
  "name": "Joe's Coffee",
4
  "slug": "joes-coffee-san-francisco",
5
  "claimed": true,
6
  "location": {
7
    "lat": 37.7749,
8
    "lon": -122.4194,
9
    "address": "123 Market St",
10
    "city": "San Francisco",
11
    "state": "CA",
12
    "postal_code": "94102",
13
    "country": "US",
14
    "cross_streets": "Market & 4th"
15
  },
16
  "contact": {
17
    "phone": "+1-415-555-0123",
18
    "website": "https://joescoffee.com"
19
  },
20
  "categories": [
21
    { "id": "coffee", "name": "Coffee & Tea" },
22
    { "id": "breakfast", "name": "Breakfast & Brunch" }
23
  ],
24
  "rating": 4.5,
25
  "review_count": 1247,
26
  "price_level": 2,
27
  "hours": {
28
    "monday": [{ "open": "07:00", "close": "20:00" }],
29
    "tuesday": [{ "open": "07:00", "close": "20:00" }],
30
    "is_open_now": true,
31
    "special_hours": [{ "date": "2024-12-25", "is_closed": true }]
32
  },
33
  "photos": [
34
    {
35
      "id": "photo_xyz",
36
      "url": "https://cdn.example.com/photos/xyz.jpg",
37
      "caption": "Interior",
38
      "user_id": "user_123"
39
    }
40
  ],
41
  "attributes": {
42
    "wifi": true,
43
    "outdoor_seating": true,
44
    "parking": "street",
45
    "noise_level": "moderate",
46
    "good_for": ["working", "casual_dining"],
47
    "accepts": ["credit_cards", "apple_pay"]
48
  },
49
  "highlights": ["Great for working remotely", "Excellent espresso"]
50
}

Submit Review

Endpoint: POST /api/v1/businesses/{business_id}/reviews

Request:

1
{
2
  "rating": 4,
3
  "text": "Great coffee and atmosphere. The baristas are friendly and the WiFi is fast. Perfect spot for remote work.",
4
  "photos": ["upload_token_1", "upload_token_2"]
5
}

Response (201 Created):

1
{
2
  "id": "review_def456",
3
  "business_id": "biz_abc123",
4
  "user": {
5
    "id": "user_789",
6
    "name": "John D.",
7
    "review_count": 42,
8
    "photo_url": "https://cdn.example.com/users/789.jpg"
9
  },
10
  "rating": 4,
11
  "text": "Great coffee and atmosphere...",
12
  "photos": [{ "id": "photo_1", "url": "https://cdn.example.com/..." }],
13
  "created_at": "2024-01-15T10:30:00Z",
14
  "status": "pending_moderation"
15
}

Error Responses:

• 400 Bad Request: Rating out of range (1-5), text too short (<50 chars) or too long (>5000 chars)
• 401 Unauthorized: Not authenticated
• 403 Forbidden: User has already reviewed this business
• 429 Too Many Requests: Review rate limit (5/day per user)

Pagination Strategy

Cursor-based pagination (chosen over offset):

• Why: Offset pagination breaks when data changes between pages. With 300K new reviews/day, offset=1000 returns different results seconds apart.
• Implementation: Cursor encodes the last seen sort key (e.g., {score: 4.5, id: "biz_xyz"}).
• Trade-off: Can’t jump to arbitrary pages, but provides consistent results.

1
{
2
  "cursor": "eyJzY29yZSI6NC41LCJpZCI6ImJpel94eXoifQ==",
3
  "has_more": true
4
}

API Response Optimization

Field inclusion strategy:

• Default response includes fields needed for list views
• ?expand=hours,attributes,photos for detail views
• Reduces payload size by 60% for search results

Denormalization decisions:

• Include distance_meters in search results (requires computation anyway)
• Include is_open_now (computed from hours, but clients need it)
• Exclude full hours object from search (add via ?expand=hours)

Data Modeling

Business Schema

Primary Store: PostgreSQL (ACID for business data integrity)

1
CREATE TABLE businesses (
2
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
3
    name VARCHAR(255) NOT NULL,
4
    slug VARCHAR(255) UNIQUE NOT NULL,
5

6
    -- Location
7
    latitude DECIMAL(10, 8) NOT NULL,
8
    longitude DECIMAL(11, 8) NOT NULL,
9
    geohash VARCHAR(12) GENERATED ALWAYS AS (
10
        ST_GeoHash(ST_SetSRID(ST_MakePoint(longitude, latitude), 4326), 12)
11
    ) STORED,
12
    address_line1 VARCHAR(255),
13
    address_line2 VARCHAR(255),
14
    city VARCHAR(100),
15
    state VARCHAR(100),
16
    postal_code VARCHAR(20),
17
    country CHAR(2) NOT NULL,
18

19
    -- Business info
20
    phone VARCHAR(20),
21
    website VARCHAR(500),
22
    price_level SMALLINT CHECK (price_level BETWEEN 1 AND 4),
23

24
    -- Aggregates (denormalized for read performance)
25
    rating_avg DECIMAL(2, 1) DEFAULT 0,
26
    review_count INTEGER DEFAULT 0,
27
    photo_count INTEGER DEFAULT 0,
28

29
    -- Status
30
    claimed BOOLEAN DEFAULT FALSE,
31
    owner_id UUID REFERENCES users(id),
32
    status VARCHAR(20) DEFAULT 'active',
33

34
    created_at TIMESTAMPTZ DEFAULT NOW(),
35
    updated_at TIMESTAMPTZ DEFAULT NOW()
36
);
37

38
-- Geospatial index for PostGIS queries
39
CREATE INDEX idx_businesses_location ON businesses
40
    USING GIST (ST_SetSRID(ST_MakePoint(longitude, latitude), 4326));
41

42
-- Geohash prefix index for simple lookups
43
CREATE INDEX idx_businesses_geohash ON businesses (geohash varchar_pattern_ops);
44

45
-- Category lookups
46
CREATE INDEX idx_businesses_city_status ON businesses (city, status)
47
    WHERE status = 'active';

Business Hours Schema

1
CREATE TABLE business_hours (
2
    business_id UUID REFERENCES businesses(id) ON DELETE CASCADE,
3
    day_of_week SMALLINT NOT NULL CHECK (day_of_week BETWEEN 0 AND 6),
4
    open_time TIME NOT NULL,
5
    close_time TIME NOT NULL,
6
    PRIMARY KEY (business_id, day_of_week, open_time)
7
);
8

9
CREATE TABLE business_special_hours (
10
    business_id UUID REFERENCES businesses(id) ON DELETE CASCADE,
11
    date DATE NOT NULL,
12
    is_closed BOOLEAN DEFAULT FALSE,
13
    open_time TIME,
14
    close_time TIME,
15
    PRIMARY KEY (business_id, date)
16
);

Categories Schema

1
CREATE TABLE categories (
2
    id VARCHAR(50) PRIMARY KEY,
3
    name VARCHAR(100) NOT NULL,
4
    parent_id VARCHAR(50) REFERENCES categories(id),
5
    level SMALLINT NOT NULL DEFAULT 0
6
);
7

8
CREATE TABLE business_categories (
9
    business_id UUID REFERENCES businesses(id) ON DELETE CASCADE,
10
    category_id VARCHAR(50) REFERENCES categories(id),
11
    is_primary BOOLEAN DEFAULT FALSE,
12
    PRIMARY KEY (business_id, category_id)
13
);
14

15
CREATE INDEX idx_business_categories_category ON business_categories (category_id);

Reviews Schema

1
CREATE TABLE reviews (
2
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
3
    business_id UUID NOT NULL REFERENCES businesses(id),
4
    user_id UUID NOT NULL REFERENCES users(id),
5
    rating SMALLINT NOT NULL CHECK (rating BETWEEN 1 AND 5),
6
    text TEXT NOT NULL CHECK (char_length(text) BETWEEN 50 AND 5000),
7

8
    -- Moderation
9
    status VARCHAR(20) DEFAULT 'pending',
10
    moderation_score DECIMAL(3, 2),
11
    moderated_at TIMESTAMPTZ,
12

13
    -- Engagement
14
    useful_count INTEGER DEFAULT 0,
15
    funny_count INTEGER DEFAULT 0,
16
    cool_count INTEGER DEFAULT 0,
17

18
    created_at TIMESTAMPTZ DEFAULT NOW(),
19
    updated_at TIMESTAMPTZ DEFAULT NOW(),
20

21
    UNIQUE (business_id, user_id)
22
);
23

24
CREATE INDEX idx_reviews_business ON reviews (business_id, created_at DESC)
25
    WHERE status = 'approved';
26
CREATE INDEX idx_reviews_user ON reviews (user_id, created_at DESC);
27
CREATE INDEX idx_reviews_pending ON reviews (status, created_at)
28
    WHERE status = 'pending';

Elasticsearch Index Mapping

1
{
2
  "mappings": {
3
    "properties": {
4
      "id": { "type": "keyword" },
5
      "name": {
6
        "type": "text",
7
        "analyzer": "standard",
8
        "fields": {
9
          "keyword": { "type": "keyword" },
10
          "autocomplete": {
11
            "type": "text",
12
            "analyzer": "autocomplete"
13
          }
14
        }
15
      },
16
      "location": { "type": "geo_point" },
17
      "geohash": { "type": "keyword" },
18
      "city": { "type": "keyword" },
19
      "country": { "type": "keyword" },
20
      "categories": { "type": "keyword" },
21
      "price_level": { "type": "integer" },
22
      "rating_avg": { "type": "float" },
23
      "review_count": { "type": "integer" },
24
      "attributes": {
25
        "type": "object",
26
        "properties": {
27
          "wifi": { "type": "boolean" },
28
          "outdoor_seating": { "type": "boolean" },
29
          "parking": { "type": "keyword" }
30
        }
31
      },
32
      "hours": {
33
        "type": "nested",
34
        "properties": {
35
          "day": { "type": "integer" },
36
          "open": { "type": "integer" },
37
          "close": { "type": "integer" }
38
        }
39
      },
40
      "updated_at": { "type": "date" }
41
    }
42
  },
43
  "settings": {
44
    "analysis": {
45
      "analyzer": {
46
        "autocomplete": {
47
          "type": "custom",
48
          "tokenizer": "standard",
49
          "filter": ["lowercase", "autocomplete_filter"]
50
        }
51
      },
52
      "filter": {
53
        "autocomplete_filter": {
54
          "type": "edge_ngram",
55
          "min_gram": 2,
56
          "max_gram": 20
57
        }
58
      }
59
    }
60
  }
61
}

Database Selection Rationale

Sharding Strategy

PostgreSQL (if needed at scale):

• Shard by country or region for geographic locality
• Most queries are region-scoped (users search near their location)
• Cross-region queries (rare) handled by query router

Elasticsearch:

• Shard by geohash prefix (e.g., first 2 characters)
• 256 shards globally (00-ff in hex, or geographic prefixes)
• Enables routing queries to relevant shards only

Low-Level Design: Geospatial Search

Search Flow

Elasticsearch Query Construction

Basic geo query:

1
{
2
  "query": {
3
    "bool": {
4
      "must": [{ "match": { "status": "active" } }],
5
      "filter": [
6
        {
7
          "geo_distance": {
8
            "distance": "5km",
9
            "location": {
10
              "lat": 37.7749,
11
              "lon": -122.4194
12
            }
13
          }
14
        }
15
      ]
16
    }
17
  },
18
  "sort": [
19
    {
20
      "_geo_distance": {
21
        "location": { "lat": 37.7749, "lon": -122.4194 },
22
        "order": "asc",
23
        "unit": "m"
24
      }
25
    }
26
  ]
27
}

With category and attribute filters:

1
{
2
  "query": {
3
    "bool": {
4
      "must": [{ "match": { "status": "active" } }],
5
      "filter": [
6
        {
7
          "geo_distance": {
8
            "distance": "5km",
9
            "location": { "lat": 37.7749, "lon": -122.4194 }
10
          }
11
        },
12
        { "terms": { "categories": ["coffee", "cafe"] } },
13
        { "term": { "attributes.wifi": true } },
14
        { "range": { "price_level": { "lte": 2 } } }
15
      ]
16
    }
17
  }
18
}

“Open now” filter (complex):

The “open now” query requires knowing the current day/time in the business’s timezone:

1
{
2
  "query": {
3
    "bool": {
4
      "filter": [
5
        {
6
          "nested": {
7
            "path": "hours",
8
            "query": {
9
              "bool": {
10
                "must": [
11
                  { "term": { "hours.day": 1 } },
12
                  { "range": { "hours.open": { "lte": 1030 } } },
13
                  { "range": { "hours.close": { "gt": 1030 } } }
14
                ]
15
              }
16
            }
17
          }
18
        }
19
      ]
20
    }
21
  }
22
}

Design decision: Store hours as integer (HHMM format: 1030 = 10:30 AM) for efficient range queries. Handle timezone conversion at query time, not storage time.

Geospatial Caching Strategy

Cache structure:

1
Key: geo:search:{geohash_prefix}:{category}:{filters_hash}
2
Value: [business_id_1, business_id_2, ...]
3
TTL: 5 minutes

Why cache by geohash prefix:

• Queries within same ~1km area hit same cache entry
• 6-character geohash prefix provides good locality
• Different filter combinations get separate cache keys

Cache invalidation:

• Business update → Invalidate all cache keys containing that business
• New business → No invalidation needed (TTL handles staleness)
• Trade-off: 5-minute staleness acceptable for discovery use case

Ranking Algorithm

Multi-signal ranking formula:

Where:

• $f_{distance} = 1 - \frac{distance}{max\_radius}$ (closer = higher score)
• $f_{rating} = \frac{rating - 1}{4}$ (normalized 0-1)
• $f_{reviews} = \frac{\log(review\_count + 1)}{\log(max\_reviews + 1)}$ (log-scaled)
• $f_{recency} = e^{-\lambda \cdot days\_since\_review}$ (exponential decay)
• $f_{personal}$ = personalization signal (0-1)

Default weights (tuned via A/B testing):

Elasticsearch function_score implementation:

1
{
2
  "query": {
3
    "function_score": {
4
      "query": {"bool": {"filter": [...]}},
5
      "functions": [
6
        {
7
          "gauss": {
8
            "location": {
9
              "origin": {"lat": 37.77, "lon": -122.41},
10
              "scale": "2km",
11
              "decay": 0.5
12
            }
13
          },
14
          "weight": 25
15
        },
16
        {
17
          "field_value_factor": {
18
            "field": "rating_avg",
19
            "factor": 1,
20
            "modifier": "none",
21
            "missing": 3
22
          },
23
          "weight": 30
24
        },
25
        {
26
          "field_value_factor": {
27
            "field": "review_count",
28
            "factor": 1,
29
            "modifier": "log1p",
30
            "missing": 1
31
          },
32
          "weight": 20
33
        }
34
      ],
35
      "score_mode": "sum",
36
      "boost_mode": "replace"
37
    }
38
  }
39
}

Handling Edge Cases

Sparse areas (few results):

• If < 10 results within radius, automatically expand to 2× radius
• Cap at 50km to prevent global searches
• Return expanded_radius: true in response metadata

Dense areas (too many results):

• Pre-filter by quality threshold (rating > 3.0, review_count > 5)
• Use stricter ranking to surface best options
• Never return more than 1000 candidates to ranker

Boundary problems:

• Elasticsearch’s geo_distance handles great-circle distance correctly
• No geohash boundary issues (unlike raw geohash queries)

Timezone handling for “open now”:

• Store business timezone in database
• Query-time conversion: UTC now → business local time
• Handle DST transitions correctly

Low-Level Design: Review System

Review Submission Flow

Spam Detection Signals

Thresholds:

• Score < 0.3: Auto-approve
• Score 0.3-0.7: Auto-approve with flag for sampling
• Score > 0.7: Manual review required

Rating Aggregation

Naive average problems:

• Business with 1 review (5 stars) ranks above business with 1000 reviews (4.8 avg)
• New businesses have unstable ratings

Bayesian average solution:

Where:

• $C$ = confidence parameter (typically 10-50)
• $m$ = prior mean (global average, ~3.7)
• $n$ = number of reviews

Example:

• New business: 2 reviews, both 5 stars
• Naive: 5.0
• Bayesian (C=10, m=3.7): $(10 \times 3.7 + 10) / (10 + 2) = 4.0$

This prevents new businesses with few perfect reviews from dominating rankings.

Review Update Consistency

Challenge: When a review is approved, multiple systems need updating:

1. PostgreSQL: review status
2. PostgreSQL: business rating_avg, review_count
3. Elasticsearch: business document
4. Cache: invalidate relevant entries

Solution: Transactional outbox pattern

1
BEGIN;
2
  -- Update review
3
  UPDATE reviews SET status = 'approved' WHERE id = $1;
4

5
  -- Update business aggregates
6
  UPDATE businesses
7
  SET rating_avg = (SELECT AVG(rating) FROM reviews WHERE business_id = $2 AND status = 'approved'),
8
      review_count = (SELECT COUNT(*) FROM reviews WHERE business_id = $2 AND status = 'approved')
9
  WHERE id = $2;
10

11
  -- Write to outbox for async propagation
12
  INSERT INTO outbox (event_type, payload)
13
  VALUES ('ReviewApproved', '{"review_id": "...", "business_id": "..."}');
14
COMMIT;

A separate process reads the outbox and updates Elasticsearch + invalidates caches.

Consistency window: ~1-5 seconds for search index, but PostgreSQL is immediately consistent for direct business profile reads.

Frontend Considerations

Search Results Data Structure

Optimized for list rendering:

1
interface SearchState {
2
  // Normalized entities
3
  businesses: Record<string, Business>
4

5
  // Search result ordering
6
  resultIds: string[]
7

8
  // Pagination
9
  cursor: string | null
10
  hasMore: boolean
11

12
  // Search params (for cache key)
13
  searchParams: {
14
    lat: number
15
    lon: number
16
    radius: number
17
    filters: Record<string, unknown>
18
  }
19

20
  // UI state
21
  isLoading: boolean
22
  error: string | null
23
}

Why normalized:

• Moving between list and detail views doesn’t duplicate data
• Updates to a business (e.g., from detail view) reflect in list
• Efficient React renders with reference equality

Map Integration

Marker clustering for dense areas:

• 50+ markers on mobile degrades performance
• Cluster markers when zoom level shows > 30 businesses in viewport
• Expand clusters on zoom or tap

Viewport-based loading:

1
interface MapSearchParams {
2
  bounds: {
3
    ne: { lat: number; lon: number }
4
    sw: { lat: number; lon: number }
5
  }
6
  zoom: number
7
}
8

9
// Debounce map move events (300ms)
10
// Only fetch when bounds change significantly (> 20% new area)

Offline Considerations

Cache strategy for mobile:

• Cache last 5 search results (businesses + basic details)
• Pre-fetch business details for top 10 search results
• Store ~50MB of data for offline browsing

Service worker strategy:

1
// Cache search results with network-first, cache-fallback
2
// Cache business details with stale-while-revalidate
3
// Never cache review submission (must be online)

Real-Time Updates

When needed:

• Review count changes (low priority, poll every 5 min)
• Business hours during edge times (near open/close)
• “Popular times” if implemented

When NOT needed:

• Real-time review streaming (batch updates fine)
• Live rating changes (too volatile, confusing UX)

Infrastructure

Cloud-Agnostic Architecture

AWS Reference Implementation

Multi-Region Strategy

Active-active for reads:

• Each region has full read replicas
• Users routed to nearest region
• Search queries served locally

Primary region for writes:

• Reviews written to primary region
• Async replication to other regions (< 5s lag)
• Business updates are infrequent, higher latency acceptable

Failover:

• Route 53 health checks detect region failure
• Automatic failover to secondary region
• RTO: < 1 minute, RPO: < 30 seconds

Cost Optimization

Common Pitfalls

1. Geohash Boundary Issues

Problem: Query at cell boundary misses nearby businesses in adjacent cells.

Cause: Querying only the target geohash cell without neighbors.

Fix: Always query target cell + 8 surrounding cells, or use proper geo_distance queries that handle boundaries correctly.

2. Rating Manipulation

Problem: Business owners create fake accounts to boost ratings.

Cause: No detection of review authenticity.

Fix: Multi-signal spam detection, IP/device fingerprinting, account age requirements, manual review sampling.

3. Stale Search Results

Problem: Newly added businesses don’t appear in search for hours.

Cause: Elasticsearch index not refreshed frequently enough.

Fix: Near-real-time indexing (refresh_interval: 1s for hot data), or explicit refresh for critical updates.

4. “Open Now” Timezone Bugs

Problem: Businesses show as open/closed at wrong times.

Cause: Storing hours in wrong timezone or not handling DST.

Fix: Store timezone with business, convert at query time, use proper timezone libraries (not offset math).

5. Photo Storage Costs Explosion

Problem: Storage costs grow 10x faster than expected.

Cause: Storing original photos without size limits or compression.

Fix: Resize on upload (max 2048px), generate thumbnails, use progressive JPEG, implement storage lifecycle (archive old photos).

6. Review Consistency Lag

Problem: User submits review, refreshes page, review not visible.

Cause: Async processing creates visibility delay.

Fix: Read-your-writes consistency: return pending review in user’s own view immediately, mark as “pending” until approved.

Conclusion

This design prioritizes search latency and result quality as the primary optimization targets, accepting complexity in the write path and eventual consistency for non-critical data.

Key architectural decisions:

1. Elasticsearch for geo-search rather than custom geospatial index—the 20-30ms latency overhead is acceptable when combined text/geo/attribute queries are needed
2. Denormalized aggregates (rating_avg, review_count) in business records—trades write complexity for read performance
3. Async review processing with transactional outbox—ensures eventual consistency while maintaining PostgreSQL ACID guarantees
4. Multi-signal ranking with tunable weights—enables A/B testing different ranking formulas without code changes

What this design sacrifices:

• Real-time consistency for search results (5-30 second delay acceptable)
• Sub-10ms geo query latency (custom geospatial index would achieve this)
• Perfect spam detection (manual review still required for edge cases)

Future improvements:

• Personalized search using user history and collaborative filtering
• “Popular times” using check-in and visit data
• Voice search integration for mobile
• Business insights dashboard for owners

Appendix

Prerequisites

• Distributed systems fundamentals (CAP theorem, consistency models)
• Database indexing concepts (B-trees, inverted indexes)
• Basic understanding of geospatial concepts (latitude/longitude, great-circle distance)
• Familiarity with Elasticsearch or similar search engines

Terminology

Summary

• Proximity search requires specialized geospatial indexing; Elasticsearch’s geo_distance query provides good balance of features and performance
• Multi-signal ranking (distance + rating + reviews + recency) produces better results than distance alone
• Review systems need async processing with spam detection to maintain quality at scale
• Denormalization and caching are essential for sub-100ms search latency
• Eventual consistency (< 30 seconds) is acceptable for discovery use cases but requires read-your-writes for user’s own content

References

• Elasticsearch Geo Queries Documentation - Official guide to geo_distance, geo_bounding_box, and geo_shape queries
• Google S2 Geometry Library - Spherical geometry library used by Google Maps
• Uber H3: Hexagonal Hierarchical Geospatial Indexing - Uber’s evolution from geohash to hexagonal cells
• Yelp Engineering Blog: Search Architecture - Insights into Yelp’s Elasticsearch usage
• PostGIS Documentation - Geospatial extension for PostgreSQL
• Foursquare Pilgrim SDK - Real-world venue detection at scale
• Building a Recommendation System at Yelp - Personalization approaches
• Wilson, E.B. (1927). “Probable Inference, the Law of Succession, and Statistical Inference” - Foundation for Wilson score interval used in rating confidence