Hotel Booking System Design: Complete Architecture

A hotel reservation system lets travelers search hotels by destination and dates, price a stay, hold it, pay and receive a confirmation, while hotels manage their own inventory, rates and restrictions. Its core rule: never confirm more stays for a room type on any night than that night's sellable inventory, and give a multi-night stay all of its nights or none. The architecture that follows has two very different halves. A horizontally scaled search path reads an eventually consistent availability projection (allowed to lag about 60 seconds). A small, strongly consistent booking path has an Inventory Service allocate every night of a stay with ordered conditional updates in one database transaction, places a short-lived hold (600-second TTL) while a Booking Orchestrator authorizes and captures payment, and converts the hold into a reservation in one confirmation transaction that also writes an outbox event. Background workers expire abandoned holds and reconcile payments that outran a crash; hotel extranet and PMS updates write the same ledger in per-hotel cursor order; and the booking database is sharded by hotel_id to contain hot properties.

The unit of inventory is the room-night

A hotel does not sell "a room". It sells a room type (Deluxe, Standard) per night. A 2-night stay consumes the Deluxe inventory of night one and the Deluxe inventory of night two — two independently scarce resources requested together. If either night is sold out, the whole stay must fail; confirming night one and silently failing night two produces a reservation nobody asked for.

That gives the invariant the entire design is graded against: for every (hotel, room type, night), confirmed plus held never exceeds sellable, and a multi-night stay is allocated atomically — every night or none. Every later component — the read model, holds, the state machine, idempotency keys, the outbox, reconciliation, PMS cursors — exists to keep that sentence true under concurrency, retries, crashes and scale.

The running example

One small example is used throughout. Hotel HTL-204 in Bengaluru has 5 Deluxe rooms (room type RT-DLX). A traveler wants 2 nights: check-in 2026-11-14, check-out 2026-11-16, i.e. the nights of 11-14 and 11-15. On 11-14, 3 Deluxe rooms are still free; on 11-15, only 1 is. That single remaining room-night is where every interesting failure in this design happens: two requests want it at once, a hold on it expires just as a payment lands, a stale search result keeps advertising it, and the hotel's own PMS reports a different count for it.

Scope

In scope: destination/date search, room-type and rate-plan browsing, multi-night availability and pricing, quotes, holds, booking, payment authorization and capture, confirmation, cancellation, date modification, hotel-side rates, capacity and restrictions (stop-sell, minimum stay), and synchronization with a hotel's property-management system (PMS) or channel manager.

Out of scope beyond a mention: payment-provider internals (see the companion Payment System design; this design owns the inventory/booking boundary around payment), loyalty, dynamic-pricing algorithms, geo-search ranking, and PCI compliance details.

Most correctness bugs in hotel booking come from mixing up a handful of domain terms. Each one below becomes a separate table with its own lifetime and guarantees.

Three different promises: quote, hold, reservation

A stay is calendar nights, not elapsed hours

A "2-night stay" means two property-local calendar nights, not 48 hours. Stay dates are evaluated in the hotel's timezone (Asia/Kolkata for HTL-204) and stored as DATE values, never as a UTC timestamp plus a duration. A check_in + 48h model silently lands on the wrong night across daylight-saving transitions and produces confirmation emails whose dates disagree with the hotel's records. Nightly rates and taxes are likewise computed per local night.

Two groups of users drive the requirements — travelers and hotel operators — and both act on the same room-night inventory. A third group of requirements comes from the fact that networks, clients and services fail.

Traveler-facing

Search hotels by destination, check-in/check-out dates and occupancy, with filters (price, amenities), sorting and pagination. View a property, its room types, rate plans and policies, and availability for every night of the requested stay, not just check-in night. Get a reproducible quote: nightly rates, taxes and fees, currency, cancellation policy, price version and expiry. Hold the stay while paying, book it with payment authorized and captured, and receive a confirmation. View bookings, cancel per the rate plan's policy, and modify dates or room type.

Hotel-operator-facing

Publish room types, rate plans, nightly rates and capacity. Close dates (stop-sell) and set minimum-stay or closed-to-arrival restrictions. Optionally connect a property-management system (PMS) or channel manager that pushes capacity and rates because the hotel also sells through other channels.

Robustness requirements

Tolerate double-clicks, client retries after timeouts, duplicated or out-of-order payment webhooks, delayed events, and a crash at any point of the booking pipeline — without losing a paid booking, charging twice, or selling a room-night twice. These are requirements, not edge cases: they determine the state machine and transaction boundaries.

The targets below are illustrative; what matters is the split they encode. Search tolerates staleness and must be cheap at high volume. Allocation and confirmation tolerate nothing but are low volume.

Cost follows the same split. Search, with thousands of queries per second, is where compute, caching and CDN money goes. Booking, with tens of requests per second, is where engineering rigor goes: transactions, constraints, idempotency, reconciliation.

Every number is a labeled assumption chosen for the right order of magnitude. The estimate's real job is to show which problem is hard: not storage, not aggregate write throughput, but read volume on one side and single-row contention on the other.

Inventory rows

Assume 50,000 properties with 3 room types each: 150,000 room types. With a 400-day bookable horizon, the authoritative ledger holds 150,000 × 400 = 60,000,000 room-night rows. At ~80 bytes per row that is ~4.8 GB, ~10 GB with indexes — small. Prices live in a separate DailyRate table (2 rate plans on average: 120,000,000 rows) because prices change when a hotelier edits them, whereas inventory rows change on every hold, confirmation, expiry and cancellation; keeping them apart means a price update never touches a hot inventory row.

Search traffic

Assume 25,000,000 searches per day: 25,000,000 / 86,400 ≈ 289 QPS on average. Travel search is diurnal and seasonal; with a 6× peak factor, 289 × 6 ≈ 1,734, rounded to ~1,800 QPS. Travelers compare 2-3 properties per search, so full-stay availability reads run at roughly 1,800 × 3 = 5,400 QPS at peak, and a holiday surge can triple search again.

Booking traffic

Assume 2.5% of searches lead to a booking attempt. At peak: 1,800 × 2.5% = 45 attempts/s. Per day: 25,000,000 × 2.5% = 625,000 attempts, of which ~90% succeed (the rest lose a race, are declined or abandoned): ≈ 562,500 confirmed reservations/day. Each attempt runs about three short write transactions (hold, booking-attempt insert, confirmation), so the primary sees on the order of 45 × 3 ≈ 135 write transactions/s at peak, plus expiries and cancellations — comfortably within one well-provisioned relational primary.

The real hot spot: one row

Aggregate write volume is modest, but it is not evenly spread. During a city-wide conference, the single row (HTL-204, RT-DLX, 2026-11-15) may see 50-200 allocation attempts within a few seconds, because every multi-night request covering that date touches it. Row-level locking serializes them. If one allocation transaction holds the row lock for 2-5 ms, that row can process roughly 200-500 allocations per second — enough, provided no transaction ever holds the lock across a network call. Capacity planning for the booking path is about per-row critical-section time, not cluster QPS.

Derived volumes

Read model: 150,000 room types × 400 nights × ~20 bytes ≈ 1.2 GB, which fits in memory with room for replication. Events: each attempt emits about 4 outbox events (hold created, hold consumed or expired, reservation confirmed, notification), 625,000 × 4 = 2,500,000 events/day ≈ 29/s average and low hundreds per second at peak. Transactional storage: 562,500 × 365 ≈ 205,000,000 reservations/year at ~1.5 KB each (reservation, nights, attempt, payment reference, events) ≈ 307 GB/year.

Each entity represents one distinct fact. The room-night ledger is the only scarce resource; quotes, holds and reservations are different objects precisely because they make different promises.

Notice the shape: RoomNightInventory is referenced by the booking path directly (inside transactions) and by the search path only indirectly (through the projection). The booking tables — inventory, holds, attempts, reservations and outbox — live in one database per hotel shard, so every booking step is a local ACID transaction; no distributed transaction is ever needed.

Read endpoints say how fresh they are; write endpoints carry an Idempotency-Key and return errors that name the exact reason. Both properties come straight from the requirements.

Search (served from the read model)

Full-stay availability

Quote

Hold

Book

Cancel and modify

Hotel-side restriction

Error taxonomy

Start with the simplest design that meets the functional requirements, then let concrete limits justify each addition. Skipping straight to the final architecture hides the reasoning that makes it defensible.

One application service and one relational database holding hotels, room types, rates, room_night_inventory and reservations. Search is a SQL query over hotels and inventory for the requested dates. Booking reads each requested night, checks that it has a free unit, then writes:

For a handful of hotels and bookings a day this is the right amount of infrastructure, and the logic looks correct on a whiteboard. It breaks along four lines as traffic and concurrency grow:

Problem: search is about 40 times the booking volume, and it tolerates a minute of staleness; booking needs exact numbers but is small. Serving both from one database makes the critical path pay for the browsing path.

Simplest options first. Read replicas move search load off the primary but keep the same normalized row layout, so every query still aggregates per-night rows across thousands of properties, and replica lag is unbounded rather than contractual. A cache-aside TTL cache in front of search queries helps hot queries, but date-range × occupancy × filter combinations have a low hit rate and misses still land on the database. A periodic full rebuild of a search index from 60M rows is simple but slow and wasteful, since only a tiny fraction of rows change between rebuilds.

Chosen: an incrementally maintained projection. Every transaction that changes a room-night (hold, confirmation, expiry, cancellation, hotel adjustment) also inserts an outbox row in the same transaction. An outbox relay delivers those events to a projector, which updates only the affected (hotel, room type, night) entries in a search-optimized availability read model — a search index plus an in-memory store (~1.2 GB), combined with cached rates. The freshness target is a projection lag of at most ~60 seconds, monitored as a metric, not a rebuild interval.

The staleness contract

What changes in the request flow: an API gateway routes search, property pages and availability to the Search Service, which reads only the read model and returns availability_as_of. Holds and bookings go to the booking path, which never reads the projection to decide anything. The outbox relay introduced here is reused later for notifications and refunds.

Remaining limit: the booking path is still read → check → write against the primary. The next stage shows what happens when two requests do that for the same last room-night.

Problem: two requests want the same last room-night at the same moment. With read → check → write, both can succeed, and the database may not even record that anything went wrong.

Request A and request B both want the running example's 2-night Deluxe stay. Night 11-15 has confirmed = 4 of sellable = 5. Each request runs the naive code from Stage 0:

Two reservations now exist for one room, yet the ledger says confirmed = 5: B's write overwrote A's. This is a lost update — each transaction computed a new value from a read that was stale by the time it wrote. The oversell is invisible to every counter and is discovered when two guests arrive. Writing confirmed = confirmed + 1 instead fixes the arithmetic but not the decision: the row then reads 6 / 5 — at least visibly oversold, but oversold.

The root cause is that the decision ("is a unit free?") was made in application memory, between two statements. Whether a stronger isolation level rescues it depends on the engine: PostgreSQL's REPEATABLE READ aborts the second writer of the same row with a serialization error, while MySQL InnoDB's default REPEATABLE READ lets the UPDATE proceed against the latest row. A correctness rule should not depend on that detail.

Multi-night stays make it worse

Independent per-night writes add a second failure: request B's write on 11-14 can succeed while its 11-15 write fails (or its process crashes between them), leaving a reservation for one night of a two-night stay, or an inventory decrement that no reservation explains.

Candidate fixes

Next: Stage 3 adopts the conditional update, applied to every night of the stay in one transaction.

Move the decision into the write: one conditional UPDATE per night, issued in ascending date order inside one transaction, with the stay committed only if every night matched.

What changes architecturally: an Inventory Service becomes the only component allowed to change room-night counts. Every path that allocates or releases inventory — booking, expiry, cancellation, modification, hotel adjustments — goes through its ordered, conditional operations.

Remaining limit: allocation still happens at click time, before payment. If the card is declined or the traveler abandons the payment page, a reservation exists that nobody paid for; if payment is taken first, a traveler can be charged for a room that sells out while they type. Stage 4 separates claiming from selling.

Problem: paying takes time — entering card details, 3-D Secure, a provider round trip — and can fail. The inventory decision and the payment outcome cannot happen at the same instant, so something must protect the room-nights in between, and that protection must end on its own.

A hold is a durable, expiring claim: an inventory_hold row plus held + 1 on every night of the stay, created by the same ordered conditional transaction as Stage 3. Holds count against availability (available = sellable - held - confirmed), so no one else can take those nights, but they are not sales.

What changes in the request flow: quote (Pricing/Quote Service, from cached DailyRate) → hold (Inventory Service, conditional per-night held + 1) → book. The Pricing/Quote Service is read-only; it never touches inventory.

Remaining limit: a booking now spans several steps and an external call, and each can fail separately. "Is this booking done?" no longer has a yes/no answer. Stage 5 names the states explicitly.

A booking is a lifecycle, not a boolean. Naming every state — including the awkward ones a crash can produce — is what lets each later mechanism say exactly which transition it guards.

Remaining limit: PENDING_PAYMENT spans an external, slow, sometimes ambiguous provider call. Stage 6 decides the order of operations, where transactions begin and end, and how retries avoid double charges.

Problem: the booking must coordinate a database it controls with a payment provider it does not, without a distributed transaction and without ever holding a database lock while waiting on the network.

Ordering: hold → attempt → authorize → capture → confirm

The Booking Orchestrator sequences the steps. (1) The hold already exists. (2) It durably records a booking attempt. (3) It authorizes the amount against the held stay — funds reserved, no money moved. (4) It captures. (5) It runs the confirmation transaction. Holding before paying means a traveler is never charged for nights that were not claimable; confirming only after capture means a confirmed reservation always has money behind it.

The alternative order, authorize → confirm → capture, shrinks the crash window (a failed capture on an already-confirmed reservation is cancelled and the authorization voided), and it is the natural fit for pay-at-hotel or deferred-capture rate plans. For prepaid rates this design captures first and accepts reconciliation (Stage 7) as the price of never confirming unpaid stays; Trade-offs & Decisions compares the two.

Three short transactions, never one long one

T1 — hold (Stage 4). T2 — booking attempt, inserted before any provider call. T3 — confirmation, after capture. The provider calls happen between transactions, so no row lock is ever held across the network; on a hot room-night that would serialize every other traveler behind one slow card. Each transaction is short, local and ACID; the state machine and the idempotency key tie the sequence together.

Idempotent booking attempts

The orchestrator inserts the attempt and lets the unique constraint decide, rather than reading first: two retries landing on two servers within the same millisecond cannot both win the insert. On a unique violation it loads the existing attempt. Same fingerprint and COMPLETED → return the original result. Same fingerprint and still PENDING_PAYMENT → 202, without re-authorizing. Different fingerprint → 409 IDEMPOTENCY_KEY_CONFLICT. The partial index closes the remaining gap: a client that retries with a new key for the same hold cannot start a second payment. Calls to the provider carry a provider idempotency reference derived from booking_attempt_id, so a retried authorize or capture resolves to the same charge.

Remaining limit: one window is still open. If the process dies after the provider captures but before T3 commits, money has moved and no reservation exists.

Problem: the provider captured the payment, then the orchestrator crashed before the confirmation transaction committed. The system must neither charge again nor pretend the booking exists.

After the crash, the database shows an attempt in PENDING_PAYMENT, a hold that is still ACTIVE (or about to expire), and no reservation. From the inside, that looks the same as a payment that is merely slow. Guessing in either direction is wrong: retrying with a new authorization can charge twice; writing a confirmation without checking the hold can oversell.

Sweep cadence is an SLO decision: minutes for the PENDING_PAYMENT sweep (bounded by the durability and support goals), and the provider's export schedule for the settlement comparison. Remaining limit: confirmed reservations still change after the fact — travelers cancel and change dates.

Cancellation releases inventory and starts a refund as two separate operations. Modification acquires the new nights before releasing the old ones, because a payment step sits in the middle.

Remaining limit: so far only the platform writes to the ledger. Hotels change capacity, rates and restrictions themselves, often through a PMS that also sells on other channels.

Problem: the booking path is no longer the only writer. Hotel staff edit capacity, rates and restrictions in an extranet, and a property-management system (PMS) or channel manager pushes updates because the hotel also sells elsewhere. The system must say precisely what each writer may change and who wins when they disagree.

Onboarding a hotel publishes its room types, rate plans and an initial 400-day window of inventory and rates as one idempotent, resumable adjustment batch keyed by an onboarding cursor, so a retried import cannot create duplicate room-night rows. Every adjustment writes an outbox event, so hotel-side changes reach the search read model through the same projection as bookings.

Remaining limit: everything works on one primary, but one very popular hotel can still saturate shared connections and locks for every other hotel, and a regional failure takes the booking path down.

Throughput is not the reason to scale the booking database: about 135 short write transactions per second fit a single primary (Chapter 05). The reasons are hot properties, blast radius and regional failure.

Every component below was added at a specific stage to remove a specific limit. The diagram is the Stage 0 whiteboard with all of those additions in place.

Request flows

Search. Gateway → Search Service → read model. Results carry availability_as_of; the property page shows per-night availability for the whole stay from the same projection. A quote comes from the Pricing/Quote Service with a price_version and a 10-minute expiry.

Book. POST /holds → Inventory Service runs T1: check restrictions, one conditional held + 1 per night in ascending date order, insert the hold and an outbox event → 201 HLD-… or 409/422. POST /bookings with an Idempotency-Key → Booking Orchestrator inserts the attempt (T2) → Payment Service authorizes, then captures → T3 fences the hold ACTIVE → CONSUMED, moves each night from held to confirmed, writes the reservation, completes the attempt and inserts reservation.confirmed → 201. The relay then drives the notification and the read-model update. A retry with the same key returns the same attempt's result.

Background. The Expiry Worker releases abandoned holds through the same fence; the Reconciliation Worker resolves attempts left in PENDING_PAYMENT by a crash or a slow provider.

Cancel and modify. Cancellation is a guarded CONFIRMED → CANCELLED with per-night releases and a separately tracked refund. Modification holds the added nights, settles the price difference, then swaps nights in one transaction, leaving the reservation CONFIRMED with version + 1.

Hotel sync. Extranet edits and PMS batches → Inventory Service (cursor check, adjustment or restriction rows, CHECK constraint) → outbox → read model. Conflicts that imply rooms already sold go to reconciliation.

A precise boundary is a stronger answer than a broad claim. Here is what the design guarantees, and where it deliberately stops.

The thread from Chapter 01 runs through every stage: the room-night is the unit of scarcity, a stay is a transaction over several of them, and each component exists to keep that transaction honest under concurrency, retries and failure. Architecture Deep Dive goes into the exact SQL, isolation behavior and worker designs; Trade-offs & Decisions compares the alternatives at each fork; Failure & Scale Scenarios stresses the finished design; Interview Perspective turns it into a whiteboard plan.