airbnb.js·7 scenarios
Airbnb system design case — two-sided marketplace with search (Elasticsearch + LTR re-rank), booking saga with escrow capture-on-confirm, host approval flow, snapshotted cancellation policy refunds, smart pricing nightly batch, host calendar block, and host payout 24h after check-in. Includes 2 ADRs (escrow timing on Booking Saga, cancellation policy enforcement on Calendar Service) and capacity hints on every node.
Airbnb is a classic two-sided marketplace case: guests search for places to stay, hosts publish listings, the platform coordinates availability, booking, payment, trust, messaging, reviews, support, and fraud. It is useful because it combines read-heavy discovery with low-volume but high-value booking writes. The search path wants speed, relevance, and personalization. The booking path wants correctness, idempotency, and financial safety.
At marketplace scale, assume millions of active listings, hundreds of millions of guest users, hundreds of millions of bookings per year, and up to a billion searches per day. Search RPS can be tens of thousands at peak; booking RPS may be hundreds, but every booking is a money-moving transaction that cannot double-sell a night. Photos alone can be hundreds of terabytes on CDN. Messages, reviews, fraud checks, pricing recommendations, and payouts form separate subsystems.
This case connects ::concept{slug="search-engine"}, ::concept{slug="hotel-booking"}, ::concept{slug="payment-system"}, ::concept{slug="maps-proximity"}, sagas, escrow, and marketplace trust.
Think of Airbnb as two different products sharing the same entities. Discovery is a search and ranking product. The user gives location, dates, party size, price range, amenities, and intent. The system finds candidate listings, filters by availability, enriches with price and photos, re-ranks with ML, and returns a page fast enough for interactive browsing.
Booking is an inventory and payment product. It must atomically reserve dates, enforce cancellation policy, charge or authorize payment, notify the host, create a message thread, and later pay the host. There is no single global transaction across search, calendar, payment provider, fraud engine, notifications, and messaging. The practical pattern is a saga: a sequence of local transactions with compensating actions.
Trust is the third mental model. Reviews, identity verification, fraud scoring, disputes, cancellation rules, host quality, guest risk, and support evidence make the marketplace usable. Without trust, the search and booking systems simply accelerate bad transactions.
The diagram shows Guest and Host clients entering through edge infrastructure and API Gateway. CDN serves listing photos directly because app servers should not stream media. Search Service queries Elasticsearch for geo, date, and filter candidates, enriches results through Listing Service and listing storage, then applies a learned-to-rank model.
Booking is represented by a Booking Saga Orchestrator. It talks to Calendar/Inventory Service to block dates, Payment/Payout Service to charge the guest and later pay the host, Fraud ML to evaluate risk, Postgres for reservation state, and Notification or Messaging services for user communication. Reviews and Messaging are independent services because they scale and evolve differently from reservations.
The diagram also encodes two important design decisions. First, capture-on-confirm and escrow are preferred over long payment authorization holds because many bookings happen weeks or months before check-in. Second, cancellation policy is snapshotted onto the reservation so policy changes do not rewrite old contracts.
Personalized search teaches candidate retrieval plus re-ranking. Elasticsearch or another search engine finds a few hundred candidates by geo, availability, price, and filters. Listing Service enriches with current metadata, photos, and availability. A ranker scores candidates using listing quality, price, guest history, reviews, location, conversion probability, and business constraints. The important lesson is that search is not the source of truth for booking; it is a fast discovery index.
Instant booking teaches the happy-path saga. The guest requests dates, the orchestrator checks fraud, Calendar Service creates a short hold or hard block, Payment Service captures funds, reservation state is committed, and messages/notifications are emitted. Every step needs idempotency because retries are normal.
Request-to-book teaches the non-instant path. A host can approve or decline within a time window. During that period dates may be softly held. If the host declines or times out, the hold is released and the guest is notified. Payment should not become an irreversible external side effect before the platform knows the reservation outcome.
Payout after check-in teaches escrow. The platform may charge the guest at confirmation but delay host payout until check-in plus a safety window. This protects guests from no-show hosts and gives time for fraud or dispute handling.
Bidirectional reviews teach trust mechanics. Guest and host reviews are held until both submit or the review window ends. This reduces retaliation and makes reputation more reliable.
Search freshness vs latency is a major trade-off. Fully fresh availability and pricing for every candidate would overload inventory services and slow down search. A common approach is to use a search index for broad filtering, then verify and enrich top candidates. The final booking path must re-check availability in the source of truth.
Escrow capture vs authorization hold is a payment trade-off. Authorization-only is pleasant because money is not captured early, but card network and PSP authorization windows are limited. Long bookings break that model. Capture-on-confirm with internal ledger and later payout increases compliance and treasury complexity, but it gives deterministic enforcement of refunds and cancellation policies.
Relational reservations vs event-sourced ledger is another trade-off. Reservations need strong constraints around date ranges and state transitions. Payments and refunds benefit from append-only ledger events. Mature designs often use both: relational current state for operational queries and immutable ledger events for money.
Instant booking improves conversion but increases fraud and host anxiety. Request-to-book gives hosts control but increases friction and abandonment. The platform can mix both using host settings, guest risk, listing category, and market maturity.
Airbnb itself has written about search ranking, marketplace trust, smart pricing, experimentation, and service-oriented architecture. Booking.com, Expedia, Vrbo, Agoda, and hotel reservation systems share many booking and inventory problems, but Airbnb adds stronger host/guest trust, messaging, home-specific policies, and variable listing quality.
Payment systems resemble Stripe Connect marketplace flows: guest charge, platform fee, host payout, refunds, chargebacks, KYC, AML, multi-currency settlement, and tax reporting. Search resembles a local marketplace search engine with geo ranking and personalization. Messaging resembles a compliance-sensitive chat product because contact details, fraud, and support evidence matter.
Do not trust the search index for booking availability. Search can be stale. The Calendar/Inventory service must make the final decision under a lock or constraint.
Do not double-book by checking availability and writing reservation in separate non-atomic operations. Date-range inventory needs careful modeling: per-night rows, range locks, exclusion constraints, or a purpose-built inventory service.
Do not call external payment providers without idempotency keys. Network timeouts after a charge are normal. Retrying without idempotency can double-charge guests.
Do not implement cancellation policy as mutable global logic only. If a host changes policy after booking, the reservation should keep the policy snapshot that the guest agreed to.
Do not mix reviews, messaging, payment, and booking into one monolith table because they all involve reservations. Their consistency needs, retention rules, abuse workflows, and scaling profiles differ.
Do not use the full marketplace architecture for a small property catalog or internal booking tool. A relational database with direct date constraints, a simple payment integration, and basic search may be enough.
Do not use eventual consistency for the final inventory commit when double booking is unacceptable. Eventual search is fine; eventual reservation confirmation is not.
Do not build escrow and payout infrastructure if the product can legally and operationally delegate marketplace payments to a PSP. Owning funds introduces compliance, reconciliation, fraud, tax, and support burden.
Do not force instant booking for categories where trust is low, supply is scarce, or hosts need manual approval. Product policy should follow marketplace risk, not only conversion metrics.
Read ::concept{slug="hotel-booking"} for inventory and reservation semantics, ::concept{slug="payment-system"} for ledger, idempotency, refunds, and payouts, ::concept{slug="search-engine"} for retrieval and ranking, ::concept{slug="maps-proximity"} for geo filtering, and ::concept{slug="stream-processing"} for fraud, notifications, and analytics. A good follow-up exercise is to design cancellation, dispute, and chargeback flows as separate sagas and list every compensating action.