System Design: Waitlist API for High-Demand Listings

Context

You are designing a waitlist system for a marketplace that offers date-based inventory (e.g., nightly stays). When a user selects a date for a given listing that is unavailable, they can join a per-listing, per-date waitlist. When inventory becomes available (e.g., due to a cancellation), the system should notify waitlisted users and prevent double-booking.

Assume:

• Inventory is tracked per listing per date (check-in date). Some listings may have capacity >1 per date.
• A waitlist exists per (listingId, date). Users may appear at most once per such waitlist.

Tasks

1. Define external and internal APIs:
   • REST endpoints (paths, methods, status codes)
   • gRPC service/methods
   • Request/response schemas
2. Propose data models and storage:
   • Entities/tables, indexes, and cache choices
   • How to store and order the waitlist (e.g., FIFO, priority tiers)
   • Capacity limits and deduplication
3. Explain correctness and fairness:
   • Ordering policy (FIFO with optional priority tiers) and tie-breaking
   • Idempotency for join/leave and notification-triggered booking
   • How users join/leave; expiration/TTL of entries
4. Describe the notification subsystem:
   • Push/email/SMS; user preferences (quiet hours, opt-in/out)
   • Delivery guarantees, retries, and escalation
5. Address concurrency and race conditions:
   • Prevent double-booking when capacity reappears
   • Transactions, optimistic/pessimistic locking
   • Exactly-once vs at-least-once semantics and idempotent consumers
6. Cover scalability and reliability:
   • Sharding/partitioning, hotspots, backpressure, rate limiting
   • Observability (metrics, logs, traces) and SLOs
7. Propose an end-to-end testing strategy:
   • Unit, integration, property-based, load, chaos/failure injection

Include diagrams in prose if helpful and justify trade-offs.