In this chapter, we will explore the high-level design of a platform like Yelp.

Let’s start by clarifying the requirements.

Before diving into the architecture, lets clearly define what we’re building.

Storage Estimation

Business Listings

Relatively small footprint, fits well in relational or document DBs. Queryable fields (category, rating, location) should be indexed.

Reviews

Media (Photos)

Stored in object storage like Amazon S3, not in databases. Backed by CDN for efficient global delivery.

Favorites

The proximity service follows a microservices architecture, where each core domain (Search, Listings, Reviews, Users) is managed by an independent, stateless service.

Clients

Users and business owners interact with the system through APIs using web and mobile clients. Users can search for nearby places, submit reviews, and save favorites or bookmarks, while authenticated business owners can create and update listings.

API Gateway / Load Balancer

The API Gateway acts as the single entry point for all client requests. It distributes incoming traffic across multiple service instances and handles authentication, authorization, rate limiting, and request logging.

Search Service

The Search Service handles all location-based search queries, supporting filters such as distance, category, minimum rating, and open now. It queries a Geospatial Index to locate nearby businesses within a radius and uses in-memory caching (e.g., Redis) to serve popular queries with low latency.

Search / Geospatial index

This is a specialized index that supports efficient proximity-based lookups. It stores each business's latitude and longitude, maps coordinates to business IDs, and supports fast geo-radius queries.

Listing Service

Business owners use the Listing Service to create or update listings. It handles CRUD operations for business profiles such as name, address, category, hours, and location, and writes updates to the Listings Database. It also emits events via a message queue to trigger search index updates and to invalidate or refresh cached data.

Review Service

The Review Service manages all user-generated reviews and ratings. It stores reviews in the Reviews Database, calculates and updates average ratings for businesses, and publishes events (e.g., review.created) for downstream consumers.

User Service

The User Service manages user accounts, authentication, and user-specific data like favorites and bookmarks. It stores this data in the Users Database.

Media Storage (e.g., S3)

Media Storage holds photos, logos, and media assets uploaded by business owners or users. Assets are served via CDN for fast delivery, and the media URLs are stored in the Listings or Reviews databases.

Search Cache

The Search Cache is an in-memory cache (e.g., Redis) that serves hot search queries. It improves latency and reduces load on the underlying services and databases.

Message Queue (Kafka / RabbitMQ)

The message queue powers an event-driven architecture. It decouples write operations from downstream processing, enables asynchronous updates to the search index and cache, and lets services publish and subscribe to domain events such as business.updated and review.created.

Index Updater

The Index Updater is a background consumer that listens to events from the message queue. It updates the geospatial and search index with new or modified business data, ensures eventual consistency between the primary datastore and the search layer, and can scale independently based on indexing workload.

To support millions of users, businesses, and reviews while ensuring low-latency queries and high availability, the system uses a polyglot persistence approach, choosing the right type of database for each microservice based on its data access patterns and scalability needs.

4.1 Listings Database

Stores structured metadata about each business.

Recommended Database: PostgreSQL with PostGIS works well when we want strong relational integrity plus geospatial indexing. MongoDB is a good alternative when we prefer flexible, document-based storage.

Schema: businesses

Indexing: We add a geospatial index on location, plus B-tree indexes on category (for filtered search) and average_rating (for sorting or threshold-based queries).

4.2 Reviews Database

Stores user-generated reviews and ratings.

Recommended DB: We can use either a SQL (e.g., PostgreSQL) or NoSQL database (e.g., MongoDB) since both can meet our requirements.

Schema: reviews

Indexing

Aggregation: A periodic job or event-driven update to the Listings DB recalculates average_rating.

4.3 Users Database

Stores user profiles, credentials, and favorite listings.

Recommended DB: PostgreSQL or MongoDB

Schema: users

Schema: user_favorites

4.4 Geospatial Index

Enables efficient proximity lookups based on (latitude, longitude).

Recommended Store

Stored Fields

We will discuss more on this later in the deep dive.

4.5 Media Storage

Store business images, logos, and user-uploaded photos associated with reviews.

Recommended Storage: Amazon S3 or any blob store

Metadata Storage: The image URL is stored in the Listings or Reviews DB.

Media is served via CDNs (CloudFront, Cloudflare) to reduce latency and bandwidth usage.

4.6 Caching Strategy

What to Cache

Recommended Storage: Redis Cluster

Keys

4.7 Message Queues

Enable asynchronous, decoupled communication between services.

Technology: Kafka or RabbitMQ

Common Events

Each microservice exposes a set of RESTful HTTP APIs. Authentication is handled via OAuth2 or JWT at the API Gateway level.

Let’s walk through the key APIs for each service.

5.1 Search Service

GET /search

Description: Search for nearby businesses based on location, filters and keyword.

Query Parameters:

Example Request:

Response:

5.2 Listing Service

GET /businesses/{id}

Description: Get details of a business by ID.

POST /businesses

Description: Create a new business listing (authenticated business owner).

Request Body:

PUT /businesses/{id}

Description: Update an existing business listing.

DELETE /businesses/{id}

Description: Delete a business listing (rare, admin-only or soft-delete).

5.3 Review Service

GET /businesses/{id}/reviews

Description: Get all reviews for a business (paginated).

Query Parameters:

POST /businesses/{id}/reviews

Description: Submit a review for a business.

Request Body:

PUT /reviews/{review_id}

Description: Update your review.

DELETE /reviews/{review_id}

Description: Delete your review.

5.4 Favorites (User Bookmarks)

POST /favorites/{business_id}

Description: Add a business to user’s favorites.

DELETE /favorites/{business_id}

Description: Remove a favorite.

GET /favorites

Description: Get a list of favorite businesses for the logged-in user.

Efficient proximity search is the backbone of a Yelp-like service. When a user searches for places near their current location, the system must return relevant results in milliseconds even when dealing with tens of millions of businesses.

A naive approach, scanning every record and calculating the distance from (lat, lon), is too slow. Instead, we rely on geospatial indexing to reduce the search space and enable low-latency, scalable lookups.

Let’s explore the most effective strategies and their trade-offs.

Geohash Grid Indexing

Geohashing is a widely used and efficient technique for indexing spatial data. It converts a (latitude, longitude) coordinate into a base-32 encoded string, where geographically close points share common prefixes.

This makes geohash ideal for proximity queries, enabling fast prefix-based lookups in large datasets using standard indexing mechanisms (e.g., B-tree or sorted string index).

How Geohashing Works

In our system, we typically store a 6- or 7-character geohash per business, which gives a good balance between search granularity and index size.

Database Integration

To enable fast geospatial queries using geohash:

Querying Within a Radius

To search for nearby businesses:

A geohash prefix query is effectively a range scan on a sorted string, which is significantly faster than computing lat-long distances row-by-row.

Handling Varying Data Density

Geohashing works well at global scale, but resolution should adapt based on area density:

You can dynamically adjust precision based on the user’s search radius. For example:

For faster lookups, you may store multiple geohash levels (e.g., geohash_5, geohash_6) as separate columns, avoiding the need for LIKE queries.

Scaling the Geohash Index

Geohash indexing is efficient even at large scale:

Sharding Strategy:

Caching Hot Geohash Queries

Many users search in the same locations (e.g., city centers). These hotspots can be cached for sub-millisecond lookups.

Example Redis Key Structure:

Frequently accessed geohash and filter combinations are stored in Redis or a memory cache. This reduces read load on the database and delivers instant search results for common queries.

Quad-tree Spatial Index

A Quadtree is a hierarchical spatial data structure that recursively subdivides a 2D plane into four quadrants: Northwest (NW), Northeast (NE), Southwest (SW), and Southeast (SE). Each quadrant becomes a node, which can be further subdivided if it contains more than a threshold number of data points.

This approach naturally adapts to data density:

This makes quadtrees particularly well-suited for spatial data with uneven distribution, like a city map where downtown has thousands of businesses but the outskirts have very few.

How It Works

Each node either stores data points directly or pointers to its children. The result is a tree where each node has up to 4 children, and leaf nodes represent spatial buckets.

Querying with Quadtrees

To perform a proximity search (e.g., "cafes within 2 km"):

This approach is fast and efficient. It avoids scanning irrelevant regions entirely and provides a tighter spatial fit than fixed-grid systems like geohash, especially for irregularly shaped queries.

In practice, quadtrees are typically implemented in-memory on each search server.

Example

At startup, the Search Service loads all business coordinates and builds a quadtree. When a search request arrives, it performs a quadtree traversal to return nearby results.

Trade-offs and Challenges

Despite their theoretical advantages, quadtrees come with several operational complexities:

Building the Tree

Real-Time Updates

Lack of Shared State

When to Use Quadtrees

Quadtrees can be a great fit when data changes infrequently, fast in-memory search is required, you have tight control over memory and indexing infrastructure, and you’re building a custom geo service optimized for spatial patterns.

In real-world systems, simplicity, reliability, and ease of scaling often take priority over raw algorithmic elegance. That’s why many production systems avoid quadtrees in favor of geohash-based indexing or database-native spatial indexes.

Database Spatial Index (R-Tree, etc.)

Another common approach to proximity search is to use the native geospatial indexing capabilities built into modern databases.

Instead of managing geohash encodings or building custom data structures, we let the database engine handle spatial indexing internally often using advanced data structures like R-Trees.

How Built-in Spatial Indexing Works

Databases like PostgreSQL, MySQL, and MongoDB offer geospatial data types (e.g., POINT, GEOGRAPHY) and spatial indexes optimized for proximity, containment, and range queries.

These systems abstract away the complexity of location indexing, letting you query locations with simple, intuitive functions like:

The database uses a spatial index (typically an R-Tree or variation) to quickly return relevant results.

Platform-Specific Support

PostgreSQL + PostGIS

MySQL

MongoDB

R-Tree vs Geohash Indexing

R-Tree indexes offer higher precision and flexible spatial queries, but come with slightly higher write overhead and storage complexity. Geohash, in contrast, is lighter and simpler but less precise around region boundaries.

Trade-offs and Considerations

Using built-in spatial indexing simplifies early development, but introduces a few constraints:

Our Design Choice

In our proximity service, database spatial indexes are a solid baseline, especially for early versions of the product.

However, as traffic grows and latency expectations tighten, geohash indexing is preferred for the following reasons:

We may explore quadtrees in the future if we need:

But for now, geohash provides the right balance of simplicity, performance, and scalability.

Let’s say a user opens the app and searches: "Find cafes within 2 km of my current location, open now, and rated 4+ stars."

1. Client Sends Search Request

The mobile/web client makes an HTTP GET request to the API Gateway:

2. API Gateway Routes Request

3. Search Service Checks the Cache

The Search Service constructs a cache key:

It checks Redis for a cached result.

4. Geospatial Query Execution

The Search Service:

5. Filter & Rank Results

The raw result set is filtered based on:

If needed, the Search Service fetches additional metadata (e.g., business name, thumbnail) from the Listings DB.

6. Response Construction

The final set of businesses is:

A lightweight JSON response is constructed with key business fields:

7. Cache the Result

The Search Service stores the response in Redis using the same cache key, with a TTL (e.g., 2-5 minutes) to handle repeated requests efficiently.

8. Return Response to Client

The JSON result is sent back via the API Gateway to the client.

Total response time:

Let’s walk through what happens when a business owner creates or updates a business listing (e.g., updates name, address, or hours).

1. Client Sends Request

The business owner (authenticated) sends a POST or PUT request to the API Gateway:

2. API Gateway Routes Request

3. Listings Service: Validate & Write

4. Emit Domain Event

This decouples the update from downstream processing and improves write latency.

5. Acknowledge the Client

6. Background Consumers React

Index Updater

Cache Invalidator

This consumer invalidates any cached search results or business detail views involving this listing.

Our system is architected for horizontal scalability at every layer, enabling it to handle millions of users, businesses, and real-time queries efficiently.

Let’s break this down by component:

Application Layer

All core services (Search, Listings, Reviews, Users) are stateless and run behind a load balancer. This allows us to scale linearly by adding more instances.

As traffic grows, we can spin up more containers or VMs (e.g., in a Kubernetes cluster or ECS) to match demand.

Data Layer

The data layer is partitioned (sharded) to prevent any single database instance from becoming a bottleneck:

If we’re storing 200 million business listings, we distribute them across shards using the first few characters of the geohash. Each shard manages a manageable subset (e.g., 1-5 million businesses), allowing for low-latency queries even under global scale.

Read Scalability

Reads dominate most user-facing operations (e.g., searching nearby places, viewing business details). To absorb heavy read traffic:

Our architecture is designed to keep most user-facing requests under 200ms, even at scale.

Efficient Geospatial Indexing

Our primary latency optimization starts with cutting down the search space:

Result: Most geospatial queries complete in under 10ms at the DB level, even for datasets with millions of entries.

In-Memory Caching

We aggressively cache frequently requested data using Redis and local memory caches.

Examples

Cache hit path:

Even cache misses are optimized, thanks to indexed reads and minimal post-processing.

Pagination and Payload Control

To minimize payload size and speed up response times:

This also improves perceived performance. Users see results quickly, and can request more as needed.

Global Deployment and Proximity Routing

When deployed across multiple geographic regions, we route users to their nearest datacenter or edge location:

This drastically reduces network round-trip time (RTT), often the biggest latency contributor in global apps.

For many users, local routing alone can shave off 100+ ms compared to centralized hosting.

To ensure the system remains accessible even in the face of failures, we’ve adopted a multi-layered fault-tolerant architecture that avoids single points of failure, gracefully degrades when needed, and recovers automatically.

Redundant Service Instances

All microservices (Search, Listings, Reviews, etc.) are deployed as multiple stateless instances behind load balancers:

Example: If the Search Service has 5 replicas and one goes down, traffic is rerouted without service interruption.

Resilient Data Stores

We use replicated, highly available storage systems to avoid data loss and ensure continuity:

Relational Databases

NoSQL Databases

Caches

Graceful Degradation

Even when parts of the system fail, core functionality remains available. We design for partial availability, not all-or-nothing failure.

Examples

In large-scale distributed systems, immediate consistency is expensive and often unnecessary for user-facing features that are not mission-critical.

We deliberately adopt eventual consistency in parts of the system where slight delays in synchronization are tolerable, trading off strict real-time accuracy for higher availability, faster writes, and system scalability.

Search Index Lag

When a new business is added or an existing one is updated (e.g., name or category), those changes may not immediately reflect in search results.

Why this is okay

Users may not see their newly added business in search for a few seconds to a minute, which is acceptable, and the listing is still accessible via direct URL or the dashboard. This decoupling keeps search updates off the write path, which ensures low-latency write operations and higher availability.

Review Propagation

After a user submits a new review, the review is saved immediately to the Reviews DB. However, the aggregated average rating and review count shown on business detail pages may lag slightly.

Why this is okay

Users get immediate confirmation of their review submission, and the rating or count discrepancy resolves quickly through background aggregators or cache expiration. No global locking or synchronous updates are required, which keeps the system responsive and write-scalable.

This trade-off enables the system to handle high write throughput without bottlenecks.

Cache Coherency

We allow temporary staleness in data served from caches (e.g., Redis, CDN edge caches).

Why this is okay

Users rarely notice a few seconds or minutes of delay in non-critical fields like business name or average rating. This allows for read-scaling and low-latency data access without constant DB hits.