Design a system to build marketplace Feature for Facebook
Let's look into FR
FR
1.Users should be able to create and manage profiles
2.Sellers can create product listings with:
Title, description, category, condition (new/used), location.
Price and currency.
Images/videos of the product.\
3.Buyers can:
Browse product listings by category, location, or seller.
Search products (text, keyword, category, filters like price range, distance, condition).
Sort by recency, price, popularity.
4.Integration with maps for location-based search.
5.Buyers should be able to filter listings near their location (e.g., within X km).
6.In-app messaging (chat between buyer & seller).
7.Initially: Marketplace can be listing + chat only (user arranges payment outside).
Advanced: Support in-app payments (integration with payment gateways).
8.Buyer gets notified when:
Seller responds to inquiry.
Price drops or product is updated.
Seller gets notified when:
New inquiry arrives.
Listing is about to expire.
NFR
1.System should be highly scalable to support hundreds of millions of users worldwide.
2.Should be able to handle millions of concurrent listings and searches.
3.System should be highly available
4.System should have low latency,such as search latency should return within <200 ms.
5.Listings and transactions should be durable and not lost.
Estimates
User Base: 1.5B MAU (Monthly Active Users on Facebook Marketplace – realistic since FB has ~3B MAU, but not all use Marketplace).
DAU: ~500M. Peak QPS factor: 10x of average.
Avg listing size: ~1 KB (metadata + indexes; images handled separately in blob storage/CDN).
Retention: Listings stay live for 30 days.
1. Listings Capacity
Assume 50M new listings/day (global scale).
In 30 days → ~1.5B active listings.
Storage = 1.5B × 1KB ≈ 1.5 TB just for metadata.
With indexes + replicas → ~10–20 TB.
Images → assume avg 3 images/listing × 500 KB each = 1.5 MB/listing.
For 1.5B listings → ~2.25 PB (served via CDN, not core DB).
2. Search Capacity
Assume 30% of DAU search daily → 150M searches/day.
QPS = 150M / 86,400 ≈ 1.7K QPS avg.
Peak QPS ≈ 17K QPS.
3.Storage Requirements
Listings DB: ~10–20 TB (metadata).
Images/Videos: ~2–3 PB (served via CDN).
Messages: If 500M/day × 1 KB = 500 GB/day. In 1 year → ~180 TB.
Logs/analytics: Multiple PB/year (must be in cold storage).
API’s
Let’s define the APIs for the Facebook Marketplace System we’ve been designing.
We’ll cover core domains → Listings, Search, Messaging, Notifications, Recommendations.
(We’ll keep them RESTful style for clarity, but gRPC/WebSockets could be used for real-time parts like chat & notifications.)
1. User APIs
✅ Get User Profile
GET /users/{userId}
{
"userId": "u12345",
"name": "John Doe",
"location": "San Francisco, CA",
"rating": 4.8,
"totalReviews": 125,
"profilePic": "https://cdn.fb.com/users/u12345.jpg"
}
2. Listing APIs
✅ Create Listing
POST /listings
{
"title": "iPhone 14 Pro",
"description": "Brand new, unopened box",
"price": 1100,
"currency": "USD",
"category": "Electronics",
"condition": "New",
"images": [
"https://cdn.fb.com/listings/iphone14-1.jpg",
"https://cdn.fb.com/listings/iphone14-2.jpg"
],
"location": "San Francisco, CA"
}
response {
"listingId": "l67890",
"status": "ACTIVE",
"createdAt": "2025-08-20T10:15:00Z"
}
✅ Get Listing
GET /listings/{listingId}
{
"listingId": "l67890",
"title": "iPhone 14 Pro",
"description": "Brand new, unopened box",
"price": 1100,
"currency": "USD",
"category": "Electronics",
"condition": "New",
"location": "San Francisco, CA",
"seller": {
"userId": "u12345",
"name": "John Doe",
"rating": 4.8
},
"images": [
"https://cdn.fb.com/listings/iphone14-1.jpg",
"https://cdn.fb.com/listings/iphone14-2.jpg"
],
"createdAt": "2025-08-20T10:15:00Z",
"status": "ACTIVE"
}
3. Search APIs
✅ Search Listings
GET /search?query=iphone&location=San+Francisco&radius=10&minPrice=500&maxPrice=1500&sort=recent
{
"results": [
{
"listingId": "l67890",
"title": "iPhone 14 Pro",
"price": 1100,
"currency": "USD",
"location": "San Francisco, CA",
"thumbnail": "https://cdn.fb.com/listings/iphone14-thumb.jpg",
"seller": {
"userId": "u12345",
"name": "John Doe",
"rating": 4.8
}
},
{
"listingId": "l67891",
"title": "iPhone 13 Pro",
"price": 800,
"currency": "USD",
"location": "San Jose, CA",
"thumbnail": "https://cdn.fb.com/listings/iphone13-thumb.jpg",
"seller": {
"userId": "u56789",
"name": "Jane Smith",
"rating": 4.6
}
}
],
"totalResults": 2
}
4. Messaging APIs
✅ Start Conversation
POST /messages/conversations
request{
"buyerId": "u98765",
"sellerId": "u12345",
"listingId": "l67890"
}
response {
"conversationId": "c112233",
"status": "CREATED"
}
✅ Send Message
POST /messages/conversations/{convId}
request {
"senderId": "u98765",
"text": "Hi, is this still available?",
"timestamp": "2025-08-20T11:20:00Z"
}
response {
"messageId": "m445566",
"status": "SENT"
}
✅ Get Conversation
GET /messages/conversations/{convId}
{
"conversationId": "c112233",
"messages": [
{
"messageId": "m445566",
"senderId": "u98765",
"text": "Hi, is this still available?",
"timestamp": "2025-08-20T11:20:00Z"
},
{
"messageId": "m445567",
"senderId": "u12345",
"text": "Yes, it’s available!",
"timestamp": "2025-08-20T11:21:10Z"
}
]
}
5. Notifications APIs
✅ Get Notifications
GET /notifications/users/{userId}
{
"notifications": [
{
"notificationId": "n1001",
"type": "MESSAGE",
"text": "You have a new message about iPhone 14 Pro",
"createdAt": "2025-08-20T11:22:00Z",
"read": false
},
{
"notificationId": "n1002",
"type": "PRICE_DROP",
"text": "Price dropped for item in your watchlist: iPhone 13 Pro",
"createdAt": "2025-08-20T11:25:00Z",
"read": true
}
]
}
6. Transaction APIs (Optional Advanced)
✅ Create Transaction
POST /transactions
request {
"buyerId": "u98765",
"sellerId": "u12345",
"listingId": "l67890",
"price": 1100,
"currency": "USD",
"paymentMethod": "CARD"
}
response {
"transactionId": "t556677",
"status": "PENDING",
"createdAt": "2025-08-20T11:30:00Z"
}
7. Moderation APIs
✅ Report Listing
POST /reports/listings/{listingId}
request {
"reporterId": "u98765",
"reason": "Fraudulent item",
"details": "This looks like a scam"
}
response {
"reportId": "r445566",
"status": "UNDER_REVIEW"
}
HLD
📌 Interaction Flows
🔹 Flow 1: Buyer searches and contacts seller
Buyer → Search Service:
/search?query=iphoneSearch Service fetches from Elasticsearch index.
Index is updated by Listing Service → Kafka → Search Service.
Results returned with listing + seller info.
Buyer → Messaging Service: starts conversation with seller.
Messaging Service stores conversation.
Sends event to Kafka.
Notification Service consumes event → pushes “New message” to seller.
🔹 Flow 2: Seller posts a new listing
Seller → Listing Service:
/listings(create listing).Listing metadata stored in Listings DB.
Event published to Kafka.
Search Service consumes → updates index.
Recommendation Service consumes → retrains/update personalization model.
Notification Service may alert buyers with saved searches/watchlist.
🔹 Flow 3: Buyer purchases via Marketplace
Buyer → Transaction Service:
/transactions(listingId, payment).Transaction Service:
Validates item availability with Listing Service.
Initiates payment with Payment Gateway.
On success → marks listing as SOLD.
Notification Service notifies buyer + seller.
🔹 Flow 4: Fraud detection / Moderation
Buyer → Moderation Service:
/reports/listings/{listingId}.Moderation Service stores report.
Runs ML model (fraud detection).
If suspicious → notifies Admin Dashboard + disables listing.
📌 High-Level Architecture (Interactions)
+------------------+
| User Service |
+------------------+
|
v
+------------------+ +------------------+
Buyer → | Listing Service | -----> | Search Service |
+------------------+ | +------------------+
| |
Kafka Events |
| v
+------------------+ +------------------+
| Notification Svc | | Recommendation Svc|
+------------------+ +------------------+
|
v
Push to Mobile/FB App
Buyer ↔ Messaging Service ↔ Seller
Buyer ↔ Transaction Service ↔ Payment Gateway
Buyer/Admin ↔ Moderation Service
✅ This shows clear ownership of each microservice and how they interact via APIs + events (Kafka pub/sub).
👉 Listings & Search are tightly coupled via async updates.
👉 Messaging + Notifications ensure real-time UX.
👉 Transactions & Moderation add trust & safety.
HLD
