Design Craigslist

Craigslist is a classified advertisements platform where users post, browse, search, and manage listings across categories like jobs, housing, services, and items for sale. The design challenge is not the complexity of any single feature, but building a system that handles millions of listings with fast search across geographic regions while keeping the architecture simple enough to maintain with a small team.

Functional

Post, edit, and delete listings: Authenticated users create classified ads with a title, description, category, price, location, and optional images. They can update or remove their own listings at any time. This is the core write path of the system.

The capacity numbers reveal a key insight: storage is dominated by images, not listing metadata. A listing's text is roughly 2KB, but its images can be 2-5MB. This 1000x difference means the image pipeline needs fundamentally different infrastructure than the listing database.

Traffic

500K new listings per day: A large classifieds platform. This is roughly 6 listings per second on average, well within a single database server's write capacity. Even during evening peak hours (3x average), 18 writes per second is trivial for PostgreSQL.

The API surface mirrors the core user actions: create a listing, search for listings, and manage your own listings. Every endpoint maps directly to a user intent, keeping the interface intuitive for client developers.

Listing Management

1POST /v1/listings
2Headers: Authorization: Bearer {token}
3Body: {
4title: string,
5description: string,
6category_id: number,
7price: number (optional),
8location: { city: string, state: string, zip: string },
9image_ids: [string] (optional)
10}
11Response: 201 Created { listing_id: string, created_at: ISO-8601 }

The data model is straightforward: users post listings in categories, and listings have images. The interesting decision is not the schema itself but the combination of storage technologies, each chosen for a specific access pattern.

Schema

1users
2id BIGINT PRIMARY KEY
3email VARCHAR(255) UNIQUE
4password VARCHAR(255) - bcrypt hash
5name VARCHAR(100)
6created_at TIMESTAMP
7
8listings
9id BIGINT PRIMARY KEY
10user_id BIGINT REFERENCES users(id)
11title VARCHAR(200)
12description TEXT
13category_id BIGINT REFERENCES categories(id)
14price DECIMAL(10,2)
15city VARCHAR(100)
16state VARCHAR(50)
17zip VARCHAR(10)
18status VARCHAR(20) - active, expired, deleted
19created_at TIMESTAMP
20updated_at TIMESTAMP
21
22categories
23id BIGINT PRIMARY KEY
24name VARCHAR(100)
25parent_id BIGINT REFERENCES categories(id) - NULL for top-level
26
27listing_images
28id BIGINT PRIMARY KEY
29listing_id BIGINT REFERENCES listings(id)
30image_url VARCHAR(500)
31sort_order INT

The architecture splits into three main paths: the write path (creating and managing listings), the read path (browsing and viewing listings), and the search path (querying Elasticsearch). Each path has different performance requirements, which is why they use different infrastructure.

Walking through the exact steps of each request reveals where latency hides and where failures can occur. Understanding these flows helps you explain during an interview how data moves through the system.

Listing Creation Flow

The core architectural challenge of a classifieds platform is keeping the search index fast and in sync with the listing database. Every listing change in PostgreSQL must be reflected in Elasticsearch, and this synchronization must handle failures gracefully without blocking the user experience.

Search Index Architecture

Every design decision involves a trade-off. The key to a strong interview answer is not just stating what you chose, but explaining what you gave up and why that trade-off is acceptable.

PostgreSQL + Elasticsearch vs. PostgreSQL Only

Using two data stores (PostgreSQL as source of truth, Elasticsearch for search) adds operational complexity: you must keep them in sync, monitor two systems, and handle consistency gaps. The alternative, using PostgreSQL's built-in full-text search (tsvector/tsquery), is simpler but breaks down at scale. PostgreSQL full-text search works well up to a few hundred thousand listings, but at 50M listings with 10K search QPS and multi-field faceted queries, it cannot compete with Elasticsearch's inverted indexes and distributed architecture.

Understanding failure modes is critical in interviews because it shows you have thought beyond the happy path. Each failure scenario here connects to a specific mitigation strategy.

Search Index Desync

Failure: The Elasticsearch index falls behind PostgreSQL. Newly posted listings do not appear in search, or deleted listings still show up in results.

These improvements address real scaling challenges and monetization opportunities that emerge as the platform grows. In an interview, mentioning these shows you are thinking beyond the immediate design.

Promoted Listings