Appearance
Marketplace Architecture
A marketplace platform is not one application — it's a system of interconnected services that independently manage supply, demand, matching, transactions, and trust across two sides of a market.
Why This Matters
- 🏢 Owner: Architecture decisions made in the first year determine how fast you can iterate, how reliably you handle peak load, and how expensive it is to operate. Bad architecture becomes visible when it starts costing you money and speed.
- 💻 Dev: You need to build systems where supply-side changes (new listings, availability updates) and demand-side actions (searches, bookings, purchases) can evolve independently. The architecture must handle the unique complexity of coordinating two-sided transactions.
- 📋 PM: Understanding architectural boundaries helps you plan features that span multiple services, estimate timelines accurately, and avoid scope creep from hidden dependencies.
- 🎨 Designer: Architecture defines what data is available on each screen and how fast it loads. The constraints your engineers face directly shape what UX you can design for both buyers and sellers.
The Concept (Simple)
Think of a marketplace like a busy farmers market in a town square.
You don't build one giant building to handle everything. Instead, you have separate areas: a section where farmers set up stalls (supply service), an area where shoppers browse and buy (demand service), a central information board that helps shoppers find what they need (search and matching), a cashier station where money changes hands (payment service), and a security office that handles disputes and safety (trust service).
Each area operates independently. If the cashier line gets long, you add more cashiers — you don't rebuild the entire market. If you want to add a new type of stall, you modify the supply area without touching the cashier station.
In one sentence: Marketplace architecture separates the platform into independent services for supply, demand, matching, payments, and trust so each can evolve and scale on its own.
How It Works (Detailed)
High-Level Marketplace Architecture
┌─────────────────────────────────────────────────────────────────────┐
│ MARKETPLACE PLATFORM ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ BUYER APP │ │ SELLER APP │ │ ADMIN │ │
│ │ (Web/Mobile) │ │ (Web/Mobile) │ │ DASHBOARD │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ═══════╪═══════════════════╪═══════════════════╪════════════ │
│ │ API GATEWAY │ │
│ ═══════╪═══════════════════╪═══════════════════╪════════════ │
│ │ │ │ │
│ ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐ │
│ │ SEARCH & │ │ LISTING │ │ USER │ │
│ │ DISCOVERY │ │ SERVICE │ │ SERVICE │ │
│ │ │ │ │ │ │ │
│ │ • Query │ │ • CRUD │ │ • Auth │ │
│ │ • Ranking │ │ • Media │ │ • Profiles │ │
│ │ • Filters │ │ • Categories │ │ • Verify │ │
│ │ • Recommend │ │ • Inventory │ │ • Roles │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ TRANSACTION │ │ PAYMENT │ │ MESSAGING │ │
│ │ SERVICE │ │ SERVICE │ │ SERVICE │ │
│ │ │ │ │ │ │ │
│ │ • Orders │ │ • Checkout │ │ • Inbox │ │
│ │ • Bookings │ │ • Escrow │ │ • Threads │ │
│ │ • State │ │ • Payouts │ │ • Notifs │ │
│ │ • Fulfillment│ │ • Refunds │ │ • Templates │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ REVIEW │ │ TRUST & │ │ ANALYTICS │ │
│ │ SERVICE │ │ SAFETY │ │ SERVICE │ │
│ │ │ │ │ │ │ │
│ │ • Ratings │ │ • Fraud │ │ • Events │ │
│ │ • Reviews │ │ • Moderation │ │ • Metrics │ │
│ │ • Responses │ │ • Disputes │ │ • Reports │ │
│ │ • Scores │ │ • Compliance │ │ • Dashboards │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘Monolith vs Microservices: What to Start With
Most marketplaces should start monolith, extract services as needed:
┌─────────────────────────────────────────────────────────┐
│ ARCHITECTURE EVOLUTION │
├─────────────────────────────────────────────────────────┤
│ │
│ STAGE 1: Monolith (Day 0 - ~$1M GMV) │
│ ┌─────────────────────────────────────────┐ │
│ │ Single application │ │
│ │ Single database │ │
│ │ Fast to build, easy to deploy │ │
│ │ All features in one codebase │ │
│ └─────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ STAGE 2: Modular Monolith (~$1M - $10M GMV) │
│ ┌─────────────────────────────────────────┐ │
│ │ Single deployment, but internal │ │
│ │ modules with clear boundaries │ │
│ │ Extract payments & search first │ │
│ │ Shared database with schema separation │ │
│ └─────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ STAGE 3: Services (~$10M+ GMV) │
│ ┌─────────────────────────────────────────┐ │
│ │ Extract services along domain lines │ │
│ │ Independent deployment and scaling │ │
│ │ Event-driven communication │ │
│ │ Service-specific databases │ │
│ └─────────────────────────────────────────┘ │
│ │
│ Rule: Don't extract a service until you feel the pain │
│ of it being coupled. │
│ │
└─────────────────────────────────────────────────────────┘Core Domain Services
1. Listing Service
Manages everything sellers create and maintain:
| Responsibility | Details |
|---|---|
| CRUD operations | Create, read, update, delete listings |
| Media management | Photo/video upload, processing, CDN delivery |
| Categorization | Taxonomy, tagging, attribute schemas per category |
| Inventory | Stock levels, availability calendars, booking windows |
| Pricing | Fixed pricing, dynamic pricing, promotional pricing |
| Versioning | Draft vs published, edit history, moderation queue |
2. Search and Discovery Service
The matching engine between supply and demand:
| Responsibility | Details |
|---|---|
| Indexing | Real-time index of all active listings |
| Query processing | Parse, expand, spell-correct, intent detection |
| Ranking | Multi-factor scoring (relevance, quality, personalization) |
| Filtering | Faceted search, geo-filtering, availability filtering |
| Recommendations | "Similar to", "You might like", "Popular near you" |
Tech choices: Elasticsearch or Algolia for search, Redis for caching, ML models for personalization.
3. Transaction Service
Orchestrates the lifecycle of orders and bookings:
┌─────────────────────────────────────────────────────────┐
│ TRANSACTION STATE MACHINE │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ CREATED │───▶│ PENDING │───▶│ CONFIRMED│ │
│ └──────────┘ └──────────┘ └────┬─────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ EXPIRED │ │ REJECTED │ │ IN │ │
│ └──────────┘ └──────────┘ │ PROGRESS │ │
│ └────┬─────┘ │
│ │ │
│ ┌────────────┼────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────┐│
│ │COMPLETED │ │ DISPUTED │ │CANCEL││
│ └────┬─────┘ └────┬─────┘ └──┬───┘│
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────┐│
│ │ REVIEWED │ │ RESOLVED │ │REFUND││
│ └──────────┘ └──────────┘ └──────┘│
│ │
└─────────────────────────────────────────────────────────┘4. Payment Service
Handles money flow between all parties (see Chapter 21 for deep dive):
| Responsibility | Details |
|---|---|
| Checkout | Payment capture, payment method management |
| Escrow | Hold funds between payment and fulfillment |
| Split payments | Divide payment between seller and platform |
| Payouts | Disburse funds to sellers on schedule |
| Refunds | Full/partial refund processing |
| Compliance | Tax calculation, 1099 generation, KYC |
Event-Driven Architecture
Marketplace services communicate through events, not direct calls. This keeps services decoupled:
┌─────────────────────────────────────────────────────────┐
│ EVENT-DRIVEN COMMUNICATION │
├─────────────────────────────────────────────────────────┤
│ │
│ Listing Service │
│ │ │
│ │ publishes: "listing.created" │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ EVENT BUS / QUEUE │ │
│ │ (Kafka, RabbitMQ, SQS, etc) │ │
│ └──┬──────────┬──────────┬────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Search Analytics Notification │
│ Service Service Service │
│ (reindex) (track) (alert seller) │
│ │
│ Benefits: │
│ • Services don't know about each other │
│ • Adding a new consumer doesn't change the publisher │
│ • Events can be replayed for debugging │
│ • Services can fail independently │
│ │
└─────────────────────────────────────────────────────────┘API Design for Two-Sided Platforms
Marketplaces need separate API surfaces for each audience:
| API Surface | Consumers | Key Endpoints |
|---|---|---|
| Buyer API | Buyer web/mobile apps | Search, listing detail, booking, checkout, reviews |
| Seller API | Seller web/mobile apps | Listing management, orders, analytics, payouts |
| Admin API | Internal tools | Moderation, disputes, user management, reporting |
| Public API | Third-party integrations | Listing syndication, booking widgets, data feeds |
| Webhook API | External systems | Event notifications for partners and integrations |
Database Strategy
| Service | Database Type | Why |
|---|---|---|
| Users/Listings | PostgreSQL (relational) | Structured data, complex queries, ACID transactions |
| Search | Elasticsearch | Full-text search, geo-queries, faceted filtering |
| Messaging | MongoDB or Cassandra | High write volume, flexible schema, time-series |
| Sessions/Cache | Redis | Low latency, ephemeral data, real-time counters |
| Media | S3 + CDN | Blob storage, global distribution, cost-effective |
| Analytics | ClickHouse or BigQuery | Columnar storage, fast aggregations, large datasets |
| Events | Kafka | Ordered event log, replay capability, high throughput |
In Practice
What Good Looks Like: Airbnb's Architecture Evolution
- 2008-2012: Monolith — Ruby on Rails monolith, single MySQL database. Fast to build, got them to product-market fit.
- 2012-2016: SOA transition — extracted search, payments, messaging into separate services. Enabled team autonomy.
- 2016-present: Microservices — hundreds of services, event-driven communication, dedicated search infrastructure. Supports billions in GMV.
Key lesson: They didn't start with microservices. They earned the right to add complexity by growing into it.
What Good Looks Like: Uber's Real-Time Architecture
- Dispatch service — matches riders with drivers in real-time using geo-spatial indexing
- Surge pricing service — dynamically adjusts pricing based on supply/demand ratio per zone
- ETA service — calculates arrival times using real-time traffic and driver location data
- Trip service — manages the state machine of a trip from request to completion to payment
Common Anti-Patterns
- Premature microservices — splitting into 20 services before you have 20 engineers. Start monolith, extract when it hurts.
- Shared database — multiple services reading/writing the same database tables creates invisible coupling and deployment nightmares.
- Synchronous everything — making service A call service B call service C in a chain. One slow service brings everything down. Use events.
- Ignoring the two-sided nature — building one unified data model when buyers and sellers have fundamentally different needs and access patterns.
- No API versioning — breaking mobile apps with backend changes because you didn't version your APIs from the start.
- Skipping the event bus — directly connecting services instead of using an event system, creating a tangled web of dependencies.
Technology Stack Recommendations
| Layer | Early Stage | Growth Stage | At Scale |
|---|---|---|---|
| Backend | Rails, Django, Next.js | Node.js, Go, Java | Polyglot per service |
| Database | PostgreSQL | PostgreSQL + Redis + Elasticsearch | Per-service databases |
| Search | PostgreSQL full-text | Elasticsearch | Elasticsearch + ML ranking |
| Queue | Redis/Sidekiq | RabbitMQ or SQS | Kafka |
| Storage | S3 | S3 + CDN | S3 + multi-region CDN |
| Hosting | Heroku, Railway | AWS/GCP with containers | Kubernetes |
| Payments | Stripe Connect | Stripe Connect | Custom + Stripe/Adyen |
Key Takeaways
- Start with a monolith and extract services only when you feel the pain of coupling — premature microservices add complexity without value
- The core marketplace services are: listings, search, transactions, payments, messaging, reviews, trust, and analytics
- Use event-driven architecture to keep services decoupled — publish events, let consumers decide what to do with them
- Design separate API surfaces for buyers, sellers, and admins — they have fundamentally different data needs
- The transaction service is the heart of the marketplace — model it as a state machine with clear transitions and failure handling
- Choose your database per service based on access patterns, not one-size-fits-all
- Payments should be extracted early — it's complex, regulated, and needs to be rock-solid
- Plan for separate scaling of each side — buyer traffic patterns differ from seller patterns
Action Items
- ☐ 🏢 Owner: Align on architecture stage (monolith vs modular vs services) based on current team size and GMV
- ☐ 🏢 Owner: Budget for search infrastructure — it's the highest-leverage technical investment for marketplace conversion
- ☐ 💻 Dev: Define clear domain boundaries for your core services (listings, search, transactions, payments, messaging)
- ☐ 💻 Dev: Implement an event bus from day one, even in a monolith — it makes future extraction dramatically easier
- ☐ 📋 PM: Map features to services so you understand cross-service dependencies when planning sprints
- ☐ 📋 PM: Create an API contract between buyer-facing and seller-facing teams to prevent blocking
- ☐ 🎨 Designer: Understand data availability per service — know what loads fast (cached) vs slow (computed) so you can design loading states accordingly
- ☐ 🎨 Designer: Design for both sides independently — buyer and seller experiences should feel like purpose-built apps, not one app with a role toggle