The whole design, in writing
Every step of the build above, written out: the problem each piece solves, the option that was taken and the ones that were not, the numbers, and how it fails in production.
The big idea
What is Airbnb?
A two-sided marketplace: hosts list homes, guests search by place and dates and book a stay. The reads (search) are enormous and demand geo + availability filtering; the writes (bookings) are rare but absolutely must never double-book a home.
Build a fast, filterable search over a spatial index and availability calendars, then a transactional booking path that reserves dates atomically and holds payment. Search optimizes for scale; booking optimizes for correctness.
What the new pieces do
- Guestclient
- Searches by place and dates, browses listings, and books a stay. Search is the heavy, read-mostly path; booking is rare but must be rock-solid.
Step 1 · The skeleton
List and find homes
Hosts need to publish listings and guests need to find them. Even ignoring geography and dates, you need a clean split between the catalog of homes and the act of searching it.
Guest searches massively outnumber host writes. How do you structure search vs the catalog?
Heavy search load hammering the source-of-truth DB threatens the writes (new listings, bookings) and can’t scale independently. Search should not contend with the system of record.
The gateway routes host writes to the Listings DB and guest queries to a search service reading an index derived from it. Search scales for read traffic while writes stay simple — and a search overload never threatens the source of truth.
You can’t pre-cache the combinatorial explosion of place × dates × filters, and listings/availability change constantly. You need a live searchable index, with caching layered on later for hot queries.
An API Gateway sends host writes to a Listings DB and guest queries to a Search Service that reads from it. This separation lets search scale for heavy read traffic while writes stay simple and consistent.
Why this piece earns its place
Splitting the paths is right, but notice what it concentrates: the same API Gateway now fronts a flood of browsing and the rare booking write. The moment search spikes on a popular weekend, those requests occupy every connection, worker and downstream socket the gateway has, and a booking queues behind people who are only looking. You carefully separated the data and then reunited the load at the front door. So I would give the two paths their own budgets there — separate connection pools and concurrency limits per route, with the booking route holding a small reserved share it never lends out — and shed search load first when the gateway saturates, because a guest who cannot browse retries and a guest who cannot pay leaves. The same logic sets timeouts: search should fail fast and let the guest try again, while a booking midway through committing must not be cut off by an impatient gateway. Isolation is not only about which database a request touches; it is about which queue it waits in.
What the new pieces do
- Hostclient
- Publishes a listing with photos, price and an availability calendar. Writes are infrequent compared to the flood of guest searches.
- API Gatewaybackend
- The single entry point routing searches to the search service and bookings to the booking service, behind a load balancer.
- Search Serviceservice
- Finds listings matching a location, date range, price and amenities, ranked for relevance. The most-hit service in the whole system.
- Listings DBstore
- The source of truth for listings: descriptions, photos (in blob storage), pricing rules and host info. Read constantly during search.
Step 2 · Search by place
Geo indexing
“Homes near this map area” is the core query, but computing distance to every listing on earth per search is impossibly slow. A normal database index on lat/long doesn’t handle 2D proximity well.
"Homes near this map area" is the core query. How do you avoid computing distance to every listing on earth?
A 1-D index can’t answer 2-D proximity — nearby in one axis can be far in the other, so you’d still scan and distance-check huge ranges. 2-D search needs a spatial structure.
Distance from one origin doesn’t help search from arbitrary map locations and must be recomputed per query. You need a structure indexed by region, not by distance to one point.
Geohashing turns 2-D coordinates into a sortable prefix; quadtrees split dense areas. Proximity search becomes a bounded lookup of listings in the viewport, then filter/rank that small set.
Build a spatial index — a quadtree or geohash — that buckets listings by region so you can fetch just the ones inside the viewport quickly, then filter and rank that small set.
Why this piece earns its place
The spatial index hands you one knob — how finely you cut space — and it is not free in either direction. Geohash prefix length, or the point at which a quadtree splits a cell, decides how many listings come back before any filtering happens. Cut too coarsely and a dense city lands in a single cell, so the viewport lookup returns nearly every home in that city and you do the planet-scan work one level down, in your own process. Cut too finely and an ordinary map view straddles many cells, so one query becomes many lookups plus a merge, and the index itself grows. I would tune it to a target candidate count per query rather than to a tidy number of digits, which is exactly why a quadtree is attractive — it splits only where density demands it, so a packed city centre and an empty county get different depths from the same rule. Either structure also needs the boundary case handled: a home just over a cell edge can be nearer than one inside, so a query reads the neighbouring cells too and ranks on real distance. Cell membership is a shortlist, never the answer.
- quadtreespatial split
- viewportbounded query
- msgeo lookup
What the new pieces do
- Geo Indexindex
- A spatial index that answers “listings within this map area” quickly, instead of scanning every home on earth and computing distances.
Back of the envelope
- geohash = sortable prefix
- 2-D coords → a 1-D bounded range
- quadtree splits dense areas
- a viewport query, not a planet scan
- fetch in-viewport, then filter/rank
- work on a small candidate set
Step 3 · Only what’s free
Availability calendars
Guests search by date range, so results must exclude homes already booked for those nights. Availability changes constantly as bookings happen, and it gates both search and booking.
Guests search by date range, so results must exclude homes booked for those nights. How do you model "is it free?"
A home is free some nights and taken others — a single flag can’t express a calendar. A stay spans a contiguous range of nights that must all be free.
One authoritative availability calendar per listing lets search filter by the requested range and booking later reserve against the same calendar. Modeling a date range makes both filtering and the no-double-book check natural.
Scanning and aggregating all bookings per listing on every search is far too slow on the hottest path. Maintain availability as its own authoritative, queryable calendar updated as bookings happen.
Keep a per-listing Availability calendar of open/taken nights. Search filters candidates by the requested range; booking will later reserve against the same calendar. One authoritative place for “is this home free?”.
Why this piece earns its place
This calendar quietly becomes the most contended object in the system, so the assumption worth making explicit is who is allowed to write it. It is tempting to treat it as a projection of the bookings table, but it is not: hosts block dates by hand, they import calendars from other listing sites, turnover and cleaning buffers close the night after a checkout, and minimum-stay rules make some open nights unbookable anyway. Each of those is a separate writer, and any one that edits the calendar outside the guarded path the next step builds can hand back a night that is already sold. So every mutation — host block, external import, admin fix — goes through the same reserve-and-release operation, with booking as just one caller of it. The second thing I would pin down is the horizon: a night-granular calendar per listing grows without limit if you let it, so bookings open only a bounded window into the future and past nights are archived out. And free is not one state. A night held by an in-flight booking is neither open nor sold, and search has to treat a held night as taken or it advertises inventory that is already spoken for.
What the new pieces do
- Availabilitystore
- Per-listing calendar of which nights are open or taken. Both search (filter by dates) and booking (reserve dates) depend on it being correct.
Step 4 · Never double-book
Transactional booking
Two guests try to book the same home for overlapping dates at the same instant. Without care, both succeed — and one shows up to a taken house. This is the marketplace’s cardinal sin.
Two guests try to book the same home for overlapping dates at the same instant. How do you guarantee only one wins?
A gap between check and write is the classic race — both guests see "free", both write, both think they booked. Check-then-set must be one indivisible step.
Confirming two overlapping stays means someone arrives at a taken house — the marketplace’s cardinal sin. The conflict must be prevented at write time, not reconciled after.
Check the range is free and mark it taken together, guarded by a unique (listing, night) constraint or row locks. Concurrent conflicting bookings collapse to exactly one winner; the other cleanly retries.
The Booking Service reserves the requested nights in a single atomic transaction: check the range is free and mark it taken together, guarded by a constraint or lock on the listing+dates. Concurrent conflicting bookings — exactly one wins.
Why this piece earns its place
The thing to say out loud is where this transaction ends, because the next step adds a network call to a payment provider and the instinct is to put it inside. Do not. Holding locks on a listing’s nights while waiting on a third party means one slow response freezes that home for everyone, and a provider outage freezes it until the locks time out. So the transaction commits quickly and marks the nights held against this booking; the money happens after, and a held range that never confirms is released. The nights are still exclusive — the constraint does that — they are simply not yet paid for. Two smaller details matter under real concurrency. Lock or insert the nights of a range in a consistent order, or two overlapping bookings grabbing the same rows from opposite ends deadlock instead of one of them cleanly losing. And treat the loser as a normal outcome rather than an error: the second guest should get a specific taken-dates response that re-runs their search with those nights excluded, because a generic failure plus a client retry loop turns one lost race into a stampede against the hottest listing on the site.
- atomicreserve
- 1winner per night
- 0double-bookings
What the new pieces do
- Booking Serviceservice
- Turns “I want these dates” into a confirmed reservation — atomically, so two guests can’t book the same home for overlapping nights.
Back of the envelope
- check + mark taken = 1 transaction
- no gap for a race
- unique (listing, night)
- the DB enforces one winner
- loser retries cleanly
- 0 double-bookings
Step 5 · Take the money
Payment hold & capture
Confirming a stay involves money across two parties, and payment can fail or be retried. Charging twice, or reserving dates without securing payment, both break trust.
Confirming a stay involves money and the payment can fail or be retried. How do you take it safely?
Reserving without securing funds means confirmed dates with no guaranteed payment, and no clean way to release them on failure. Tie the hold to the booking and release both if payment fails.
Hold the card to secure funds while finalizing, capture on confirmation, and release the hold and the dates if it ultimately fails. An idempotency key makes the inherently retried payment path safe from double-charges.
Charging before a booking is even confirmed means refunds, double-charges on retries, and money taken for stays that never happen. Separate auth from capture.
On booking, authorize (hold) the guest’s card; on confirmation, capture it and schedule the host payout. Use an idempotency key so a retried request never double-charges, and release the hold (and the dates) if payment ultimately fails.
Why this piece earns its place
The hard part of hold-and-capture is not the happy path, it is not knowing what happened. A request to the provider can time out after the authorization was created, so the safe assumption is that any ambiguous response might have moved money. The idempotency key makes a retry safe, but it does not tell you the answer — you still have to go and ask. So pending bookings need an owner: a reconciliation worker that takes every booking stuck in pending, queries the provider by that same key, and drives it to confirmed or released. Without one, an ambiguous timeout leaves nights held indefinitely for a stay nobody will take, and the inventory is the real hostage here, not the money. That also means the release path needs a deadline rather than a human — if the outcome is still unknown after a bounded wait, release the dates so the home can be sold and reverse the hold if it turns out to exist. And that deadline is not mine to set freely, because the hold is short-lived: an authorization is only good for a bounded window on the issuer’s side, so the wait has to end inside it. A booking still pending when the hold lapses can no longer be captured, so the worker treats a lapsed authorization as it treats a declined one — re-authorize if the guest is still there, otherwise release the nights.
What the new pieces do
- Paymentsservice
- Authorizes the guest’s card to hold funds at booking and captures on confirmation, with idempotency so a retry never double-charges.
Step 6 · Keep it fresh
Reviews & reindexing
New listings, price changes and reviews must show up in search, and ranking should reflect quality — but doing that work synchronously on the booking/listing path would slow everything down.
New listings, price changes and reviews must reach search, and ranking should reflect quality. How, without slowing writes?
Doing reindexing and review aggregation inline makes every write wait on search-index updates, coupling a fast critical path to slow propagation. These effects are eventually-consistent by nature.
Querying the source-of-truth DB per search reintroduces the read load on writes you separated in step 1, and can’t do fast ranking. Search needs its own index, kept fresh out-of-band.
Listing/booking changes flow to an event stream; consumers reindex search, roll reviews into ratings, update payouts and notify — off the request path. Writes stay fast, search stays current (eventually).
Emit listing and booking changes as events. Consumers reindex the search service, aggregate reviews into ratings, update host payouts and send notifications — all asynchronously, so the write path stays fast and search stays current.
Why this piece earns its place
An event stream is only as good as its delivery guarantees, and the realistic ones are at-least-once and not necessarily in order. So every consumer here has to be idempotent and version-aware: carry the source row’s version on the event and drop anything older than what the index already holds, or a redelivered price change will cheerfully overwrite the newer price that followed it. Reprocessing the same event twice should be a no-op, because it will happen. The second thing is that these consumers are not equals and should not share a lane. Availability and booking changes are the most perishable things on the stream — they are what keeps search from showing sold homes as free — while review aggregation and payout rollups are slow, batchy and unhurt by a delay. Put them on separate streams or partitions so a backlog in the slow work cannot head-of-line block the urgent work, which is exactly what would otherwise happen at peak, when both are heaviest. And the signal I would alert on is consumer lag, not consumer errors: a healthy consumer falling steadily behind is the failure that reaches guests, and it throws no exceptions at all.
What the new pieces do
- Eventsbus
- A stream of listing and booking changes that drives search reindexing, review aggregation, host payouts and notifications asynchronously.
Back of the envelope
- change ⇒ event
- the write path doesn’t wait
- consumers: reindex, reviews, payouts
- eventually consistent by nature
- record change ≠ propagate effects
- decoupled via the stream
Step 7 · Scale the reads
The sharp edges
Search traffic dwarfs everything and spikes seasonally and by destination; popular cities create hotspots. One listings database can’t serve it all, and recomputing identical searches is wasteful.
Add read replicas for the listings data, cache popular search results and listing pages, and shard/partition by region. Pricing and ranking can be precomputed; the rare booking path stays transactional while reads scale out horizontally.
Why this piece earns its place
“Cache popular searches” is easy to say, and the hard part is admitting what the key is. A search is a place, a date range and a set of filters, and that product is enormous — almost no two guests ask the identical question — so caching whole result sets buys a hit rate near zero, while every booking invalidates a set of entries you cannot cheaply enumerate. What actually repeats is underneath it: the listing pages themselves, the candidate set for a given map cell, photos and static content at the edge, and precomputed ranking signals like rating and popularity. Cache those, and let the per-query work be filtering and ranking over a small set. The replicas need one carve-out too. Reading availability from a replica is fine while browsing, since search was already best-effort — but the moment a guest has booked, their confirmation and trips page must read the primary, because showing someone their own reservation missing is a support ticket and, worse, a second booking attempt. Replicas serve the reads that tolerate being behind; anything a user just caused reads from where they wrote it.
You did it
You just designed Airbnb.
Everything you assembled, in order
- A gateway splitting heavy search reads from rare, careful booking writes.
- A spatial index (quadtree/geohash) makes “homes near here” a bounded query.
- Per-listing availability calendars power both date filtering and booking.
- Atomic, lock-guarded booking so overlapping stays can never double-book.
- Payment hold-then-capture with idempotency keys for safe, retryable charges.
- Event-driven reindexing and review aggregation keep search fresh asynchronously.
- Read replicas, search caching and regional sharding scale the read-heavy load.