System Design: [Booking system name]

Reference design for a hotel room and event ticket booking platform. It covers the inventory model for rooms (date-based allotments) and seats (individually identified), holds with a time to live, overbooking policy, concurrency control with optimistic and pessimistic locking and conditional writes, idempotency keys, payment integration through a saga with compensation, flash-sale traffic with a virtual waiting room, the split between the search path and the booking path, consistency boundaries, failure handling and fraud controls. It follows the structure of the System Design Document template and is pre-filled with a worked design to adapt. Replace every [bracketed] value and every row marked Example; values marked Example are assumptions. This is an engineering format, not legal, consumer-protection or payment-compliance advice.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: We sell hotel rooms from 4 000 partner properties and tickets for concerts and sports events. Last season a stadium onsale sold 312 seats twice because two application servers read the same "available" row before either wrote. The search page timed out for 18 minutes during the same onsale because availability queries ran against the booking database. Customers whose payment failed kept their seats locked for 30 minutes, and resale bots bought 40% of the best seats in the first two minutes.]

1.2 Proposed solution

[Example: Inventory lives in an inventory service that owns a strongly consistent store partitioned by event or property. A booking is a saga: hold inventory with a conditional write and a 10-minute expiry, authorise payment, confirm the hold, capture payment, issue tickets or a hotel confirmation. Every step is idempotent and has a compensating action. Search reads a denormalised availability index fed by inventory change events and is allowed to be a few seconds stale; the booking path always re-checks the source of truth. Large onsales go through a virtual waiting room that admits users at the rate checkout can sustain. Bot and fraud controls run at the waiting room and again before payment.]

1.3 Decisions requested from reviewers

2. Requirements

2.1 Functional requirements

2.2 Non-functional requirements and invariants

2.3 Out of scope

• [Example: dynamic pricing algorithms (consumed as a price service)]
• [Example: secondary-market resale and ticket transfer (separate design)]
• [Example: the double-entry ledger (see Payment Ledger System Design (system-design/design-payment-ledger))]
• [Example: channel manager integrations with property management systems beyond the allotment feed]
• [Item deferred, with the release that will take it]

3. Capacity estimation

3.1 Assumptions

3.2 Onsale throughput and admission rate

Orders needed to sell out:

At the sustainable checkout rate the sale takes about

The waiting room admits users at the rate checkout can absorb, allowing for users who browse and leave:

Most of the 2 million users will not get tickets. Admitting at 500 users/s, only about $500 \times 67 \approx 33\,500$ users are admitted before the event sells out; the rest must be told quickly and honestly (7.7), not left in a queue that cannot succeed.

3.3 Holds and contention

Active holds are bounded by inventory, not by users: at most $S = 50\,000$ seat holds exist at once. Each hold attempt touches 1 to 8 seat rows in the partition of one event, so the hottest partition sees roughly

with $k_{try} = 1.5$ hold attempts per admitted user (Example: some retry after losing a seat) and $\bar{s} = 2.5$ seats per attempt. That rate fits one well-provisioned partition but not one row lock queue, which is why 7.3 uses short conditional writes rather than long transactions.

3.4 Search

Search at $Q = 20\,000$ queries/s is served from the availability index and cache. With a cache hit ratio of 0.9, the index sees about 2 000 queries/s. The booking store sees no search traffic at all.

3.5 Hotel inventory size

3.6 Summary

4. API design

4.1 Endpoints

4.2 Request and response examples

A hold request names the inventory and carries the admission token during metered onsales; the response returns the server-set expiry and the price that the booking will be charged.

POST /v1/holds
Idempotency-Key: 8f1c2a7e-4d55-4b0e-9c61-2b1f0e9d7a10
Authorization: Bearer [token]
Content-Type: application/json

{"event_id": "evt_2291", "seats": ["A-12-07", "A-12-08"], "queue_token": "qt_9c1e4b"}

HTTP/1.1 201 Created
Content-Type: application/json

{"hold_id": "hld_77a1", "status": "held", "seats": ["A-12-07", "A-12-08"], "expires_at": "YYYY-MM-DDThh:mm:ssZ", "price": {"amount": 18000, "currency": "EUR"}}

4.3 Idempotency and errors

• The server stores the key, a hash of the request body and the response for 24 hours. The same key with the same body returns the stored response; the same key with a different body returns 422.
• A hold that loses a race returns 409 with the seats that are no longer available, so the client can offer alternatives without reloading the map.
• An expired hold returns 410 on POST /v1/bookings.
• Errors use RFC 9457 problem details with a stable type URI.

5. Data model

5.1 Entities

Seats are identified inventory (one row per seat per event). Hotel rooms are counted inventory (one row per property, room type and night).

5.2 Storage choices and invariants

6. High-level design

Two paths share the inventory events but not the store: search is fast and stale by seconds, booking is exact.

7. Detailed design

7.1 Inventory model

• Identified inventory (seats): each seat has a status (available, held, sold, blocked), the hold that owns it and a version. A seat moves available -> held -> sold, or held -> available on expiry.
• Counted inventory (room nights, general admission): one row holds allotment, held, sold and overbook_limit. A hold increments held only when the predicate still holds after the increment.
• Multi-night stays must hold every night or none. All nights of one room type at one property live in one partition, so one transaction covers them.

7.2 Holds and TTL

• A hold has expires_at set by the server. Clients see a countdown but the server clock decides.
• Expiry is enforced twice: lazily (a hold past expires_at is treated as released by every read and by the conditional write predicate) and actively (the sweeper releases it and emits inventory.released so search and the waitlist learn about it).
• A hold can be extended once while a 3-D Secure challenge is in progress, so a slow bank page does not lose the customer's seat during authorisation.
• Example TTLs: tickets 10 minutes, hotels 15 minutes, extension 5 minutes.

7.3 Concurrency control

Seat hold, all or nothing for the requested seats:

UPDATE seat
SET status = 'held', hold_id = :hold_id, held_until = :expires_at, version = version + 1
WHERE event_id = :event_id
  AND seat_id IN (:seat_ids)
  AND (status = 'available' OR (status = 'held' AND held_until < now()));
-- In the same transaction: if affected rows < requested seats, roll back and return 409.

Counted inventory hold for one night:

UPDATE room_night
SET held = held + :qty, version = version + 1
WHERE property_id = :p AND room_type = :rt AND night = :n
  AND held + sold + :qty <= allotment + overbook_limit;

Holding locks while calling a payment provider is forbidden: a slow PSP would turn into a lock queue across the whole event. The hold itself is the long-lived "lock", expressed as data with an expiry.

7.4 Idempotency

Every mutating call carries an Idempotency-Key. The booking API writes the key, request hash and a processing marker in the same transaction as the hold or booking row; a concurrent duplicate waits or receives 409 request-in-progress. Saga steps carry their own step keys (booking_id:authorise, booking_id:capture) so retries after a crash do not authorise or capture twice. The payment provider receives the step key as its own idempotency key.

7.5 Overbooking policy

Overbooking applies to counted hotel inventory only, never to seated events. Revenue management sets overbook_limit per property, room type and night from historical no-show and late cancellation rates. With allotment $N$, bookings $n$ and an independent show probability $q$, the expected number of guests who arrive is $nq$, and the risk of more arrivals than rooms is

Example: $N = 200$, no-show rate 8% so $q = 0.92$, and $n = 210$ (limit 10): mean arrivals $210 \times 0.92 = 193.2$, standard deviation $\sqrt{210 \times 0.92 \times 0.08} \approx 3.93$. With a normal approximation and continuity correction, $z = (200.5 - 193.2)/3.93 \approx 1.86$, so the probability of walking at least one guest is about 3% (the exact binomial value is about 2.4%; compute it exactly when the spreadsheet allows). Revenue management approves the acceptable walk risk; the system enforces the resulting limit, records every overbooked night and triggers the walk workflow (relocation, compensation, notification) when arrivals exceed rooms.

7.6 Booking saga and compensation

The saga is orchestrated by a durable workflow so each step survives process crashes. Steps and compensations:

A payment timeout is unknown, not failed: the orchestrator queries the PSP by idempotency key before deciding to void or proceed. Capture after confirm means a customer is never charged for a seat they did not get; the cost is that an authorisation can occasionally be voided after the customer saw a success screen for authorisation, which the UI avoids by showing success only after S4.

7.7 Flash sales and the virtual waiting room

• Users who arrive before onsale time get a random queue position when the sale opens, so refreshing early gives no advantage (NFR-08). Users arriving after opening join the back of the queue.
• The room admits users at rate $A$ (3.2), adjusted every 10 seconds by observed checkout latency and payment error rate.
• Admission issues a signed, short-lived token bound to account and device. The booking API rejects holds without a valid token during metered sales.
• When remaining inventory minus active holds reaches zero for a section, the room tells queued users that the section is sold out and offers the waitlist instead of keeping them waiting.
• The waiting room page is static and served from the CDN, so the origin sees only the token and counter calls.

7.8 Search path versus booking path

The index is fed by inventory events from the outbox. A seat map shows "likely available"; the hold is the only authoritative check.

7.9 Consistency boundaries

• Strongly consistent inside one inventory partition: one event's seats, or one property's room nights.
• A booking spanning two partitions (a hotel plus a concert package) is a saga across two holds, not a distributed transaction. Either both holds succeed or the first is released.
• Booking and payment states converge through the saga and daily reconciliation with the PSP (NFR-03); the ledger is the financial source of truth.

8. Scalability and performance

Latency budget for POST /v1/holds (target p99 250 ms):

9. Reliability, security and operations

9.1 Failure modes

See Software FMEA (ops/fmea-software) to score these, and Chaos Experiment Plan (ops/chaos-experiment) to test FM-01 and FM-02 before the first large onsale.

9.2 Security, abuse and fraud

Model the remaining threats in a Threat Model (security/threat-model).

9.3 Observability

9.4 Cost estimate

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Rollout and rollback

[Example: Migrate one venue at a time; the old and new inventory never own the same event. Run the first large onsale on the new system with a rehearsal the week before using synthetic users. Rollback for an event before onsale is a configuration switch; after onsale, the event stays on the system that sold it.]

11.3 Risks

12. Appendices

12.1 Traceability

12.2 Open questions

12.3 Glossary

12.4 References

Standard and licence note

Based on common industry practice for inventory, reservation and ticketing systems and on the references in 12.4; the Idempotency-Key header field is an IETF draft, not a published RFC. This is a reference design to adapt, with illustrative numbers; it is a format, not legal, consumer-protection or payment-compliance advice. Check the current version of every cited specification. Original text written for this collection. Template licence: MIT.