Design a Booking Waitlist

Introduction

A waitlist is a durable priority queue with business rules glued to inventory events. The interesting failures are duplicate offers for the same seat, orphaned offers after worker crashes, and notification gaps—not drawing a queue icon.

Interviewers want a clear state machine, per-resource concurrency control, and booking integration that survives retries.

How to approach

Define states and transitions on paper. Pick FIFO vs priority score (timestamp + loyalty). Walk one cancellation → one offer → accept or expire → promote next. Then failure paths: notify fails, booking API returns 503.

Interview tips

• Outbox pattern: insert offer row and outbox event in the same transaction; a relay worker pushes to email/push—reliable handoff.
• Per-resource lock or partition consumer: only one promotion pipeline per concert, flight, or slot pool at a time if ordering must be strict.
• Idempotency: accept_offer with idempotency_key; booking service dedupes final reservation creation.
• Position gaming: exact rank may invite bots—opaque bands or estimated wait time are product choices.
• Bulk cancel (e.g. weather): storm of offers—rate-limit promotions or batch into waves; be explicit about fairness.

Capacity estimation

Load	Implication
Waitlist depth per hot event	Millions of rows—index (resource_id, position) or heap by score
Offer churn	Short TTL rows and many transitions—archive terminal states to cold storage
Notification fan-out	Bursts when many slots return—queue workers sized to provider TPS

Implications: promote in batches with backpressure; do not send every email synchronously from the API thread.

High-level architecture

The waitlist API persists rows in WAITING. The inventory service emits CapacityReleased events (from cancellation or admin). A promotion worker (per shard or holding a per-resource lock) claims the event, opens a transaction, selects the next waiter, creates an OFFERED row with expires_at, commits, and writes an outbox row. The notifier sends an offer link with a signed offer_token. The user calls POST …/accept → the booking service creates the reservation (source of truth for inventory); the waitlist moves to ACCEPTED or DECLINED.

[ Booking cancel ] --> event bus --> Promotion worker (per resource serialized)
                                           |
                                           v
                                    [ Waitlist DB ]
                                    WAITING -> OFFERED (expires_at)
                                           |
                                      outbox row
                                           v
                                    [ Email/SMS worker ]
                                           |
User clicks --> POST /offers/{id}/accept --> Booking API (hold + confirm)

In the room: Emphasize that the booking service owns inventory truth—the waitlist orchestrates people, not seats, unless the problem scope says otherwise.

Core design approaches

Storage

Relational rows per (user, resource) with state, joined_at, score, offer_id. A unique constraint prevents duplicate joins.

Ordering

FIFO: joined_at plus a monotonic tie-breaker.

Priority: score descending, joined_at ascending—watch starvation; consider aging boosts for old entries.

Integration

Saga: offer accepted → booking creates reservation → on success waitlist terminal ACCEPTED; on failure → decline or retry booking with backoff, then expire the offer and promote the next person.

Detailed design

Join

1. Verify the resource is full (or the product accepts waitlist-only signup).
2. INSERT waitlist row WAITING if not exists (unique).
3. Return a position band or an opaque “you’re on the list.”

Promotion on capacity

1. Consumer receives CapacityReleased(resource_id, quantity).
2. For each unit: BEGIN; lock the resource row or use SELECT … FOR UPDATE SKIP LOCKED on the next WAITING user; create offer; set waiter to OFFERED; insert outbox; COMMIT.
3. Notify asynchronously.

Accept

1. POST with offer_token and Idempotency-Key.
2. Validate offer not expired and not already terminal.
3. Call booking POST /reservations (internal).
4. On 201 from booking: mark ACCEPTED.
5. On 409 from booking: expire offer and promote next (slot gone).

Key challenges

• Duplicate offers: two workers process the same event—idempotent event processing (event_id unique) or row locks.
• User leaves while offered: transition to CANCELLED_BY_USER if allowed, or force decline on leave.
• Payment step: tie offer TTL to the payment authorization window—coordinate timeouts with the PSP.
• Fairness under priority: document precedence rules (VIP vs FIFO tie-break).

Scaling the system

• Shard waitlist by resource_id hash or event id.
• Single consumer per hot resource (Kafka partition key = resource_id) for strict ordering.
• Backpressure: cap depth of WAITING per resource or return 410 when the list is full.

Failure handling

Failure	Mitigation
Notify fails	Retry with exponential backoff; offer still expires independently; user can see offer in app inbox
Booking 503 on accept	Retry with bounded attempts; then expire and promote next
Poison message on bus	DLQ plus alert; manual replay

API design

Endpoint	Role
POST /v1/resources/{id}/waitlist:join	Join
DELETE /v1/waitlist/{entry_id}	Leave
GET /v1/waitlist/{entry_id}	Status and active offer if any
POST /v1/offers/{id}:accept	Accept (idempotent)
POST /v1/offers/{id}:decline	Decline

POST /v1/offers/{id}:accept

Header / field	Role
Idempotency-Key	Dedup retries
payment_method_id	If payment is in scope

Diagram:

POST join --> 201 (entry_id)
       ...
event CapacityReleased --> worker --> OFFERED + notification
POST accept --> Booking API --> 201 reservation
             --> waitlist ACCEPTED

Production angles

Waitlists are fairness machines disguised as queues. Production breaks when priority rules conflict with FIFO expectations, when promotion workers are seconds behind user patience, and when offers expire in the notification channel slower than the TTL. Support tickets are existential: “I was next” is a reputation problem, not a log line.

“I was skipped” — fairness vs opaque reordering

What it looks like — Social media outrage, chargebacks, executive escalation. Audit shows a priority-tier insert or a buggy sort key that promoted someone out of strict arrival order. Users screenshot position numbers that changed without explanation.

Why it happens — Product adds VIP, loyalty, or geo boosts without documenting conflicts with FIFO marketing. Concurrent capacity events recompute ranks; off-by-one bugs in windowed queries skip rows under pagination cursors.

What good teams do — Immutable audit log per transition (from_state, to_state, reason_code, rule_version); support replay tool that read-only reconstructs position history; public copy honest about priority lanes. Postmortems treat fairness bugs as P0 even when revenue looks fine.

Offers expire before the user sees them

What it looks like — SMS arrives after offer_expires_at; push is throttled by the OS; the user opens email hours later. Conversion tanks; ops extends TTL ad hoc and accidentally breaks downstream inventory math.

Why it happens — TTL tuned for happy-path latency assumptions; third-party providers add variable delay; DND and spam filters hide channels. Worker lag between OFFERED and notification enqueue eats the same window you budgeted for human reaction time.

What good teams do — In-app inbox as primary surface with push/SMS as hints; size TTL ≥ p99 notification latency plus a human reaction budget; monitor time from CapacityReleased to delivered by channel. Extend offers idempotently with audit trails, not silent clock changes.

Promotion backlog: cancellations spike faster than workers

What it looks like — WAITING users see stale position; offers arrive in bursts hours after inventory freed. Queue depth ramps while per-pod CPU looks fine—often DB lock contention or a single hot shard serializing updates.

Why it happens — Many cancellations enqueue promotion jobs faster than workers drain; a hot event or venue row becomes a serialization point; naive SELECT FOR UPDATE over large ranges.

What good teams do — Scale workers horizontally with partition by resource_id; wave promotions to smooth notification spikes; shard hot resources or use per-event queues. Measure lag from CapacityReleased to OFFERED, offer expiry without open, and booking failure rate on accept (double tap, flaky network).

[ Many cancellations ] --> promotion worker falls behind
       --> WAITING users get offers late (SLA miss)
       --> scale workers OR shard hot resources OR wave promotions

How to use this in an interview — Pair auditability of line position with channel latency assumptions. Close with idempotency on accept—a double tap must not book twice or charge twice.

Bottlenecks and tradeoffs

• Strict FIFO vs business priority—document conflicts explicitly.
• Transparency (exact position) vs gaming risk.