Design A Hotel Booking Service - System Design

Requirements

Functional Requirements:

Allow users to search and filter hotels by location, dates, price, and amenities.
Allow users to book a hotel room for specific dates.
Display real-time room availability and prevent double-booking.
Support secure payment processing for reservations.
Allow users to manage bookings including cancellation and modification.
Allow users to leave reviews and ratings for hotels.
Allow hosts or hotel managers to list and manage properties.

Non-Functional Requirements:

Availability

Search and hotel browsing should be highly available.
Booking flow should prioritize correctness over availability.
Target:
- Search API: 99.99% availability
- Booking API: 99.95% availability
- Payment flow: 99.9% availability with retry-safe behavior

Scalability

Support millions of users, hotels, reviews, and bookings.
Read-heavy traffic pattern:
- Search, hotel detail, recommendations dominate traffic.
Booking traffic is lower volume but requires strong consistency.

Performance

Target latency:

Search hotels: p95 < 500 ms
Hotel detail page: p95 < 300 ms
Availability check: p95 < 200 ms
Booking confirmation: p95 < 2 seconds, excluding external payment latency
Review submission: p95 < 300 ms

Reliability

Booking must not double-book rooms.
Payments must be idempotent.
Booking confirmation must eventually be delivered even if notification service fails.

Resilience

Use circuit breakers around payment providers.
Use retries with exponential backoff for transient failures.
Use queues for asynchronous workflows such as emails, receipts, search indexing, and recommendations.

Fault Tolerance

Replicate databases across availability zones.
Use read replicas for search-heavy metadata reads.
Use message queues with dead-letter queues.
Use idempotency keys for booking, payment, and cancellation APIs.

Consistency

Strong consistency required for room inventory reservation.
Eventual consistency acceptable for:
- Search index
- Reviews aggregation
- Recommendations
- Analytics
- Hotel listing updates appearing in search

API Design

User Search Hotels

GET /v1/hotels/search

Query Parameters

{
  "location": "New York",
  "check_in": "2026-07-01",
  "check_out": "2026-07-05",
  "guests": 2,
  "min_price": 100,
  "max_price": 500,
  "amenities": ["wifi", "pool"],
  "sort": "price_asc",
  "page_token": "abc123"
}

Response

{
  "hotels": [
    {
      "hotel_id": "h_123",
      "name": "Central Park Hotel",
      "location": "New York",
      "rating": 4.6,
      "starting_price": 240,
      "available": true,
      "amenities": ["wifi", "gym", "pool"]
    }
  ],
  "next_page_token": "def456"
}

Get Hotel Details

GET /v1/hotels/{hotel_id}

Response

{
  "hotel_id": "h_123",
  "name": "Central Park Hotel",
  "description": "Luxury hotel near Central Park",
  "rooms": [
    {
      "room_type_id": "rt_101",
      "name": "Deluxe King",
      "base_price": 240,
      "capacity": 2,
      "amenities": ["wifi", "city_view"]
    }
  ],
  "reviews_summary": {
    "rating": 4.6,
    "review_count": 1832
  }
}

Check Availability

GET /v1/hotels/{hotel_id}/availability

Query Parameters

{
  "check_in": "2026-07-01",
  "check_out": "2026-07-05",
  "guests": 2
}

Response

{
  "hotel_id": "h_123",
  "available_rooms": [
    {
      "room_type_id": "rt_101",
      "available_count": 3,
      "nightly_price": 240,
      "total_price": 960
    }
  ]
}

Create Booking

POST /v1/bookings
Idempotency-Key: booking_req_abc123

Request

{
  "user_id": "u_123",
  "hotel_id": "h_123",
  "room_type_id": "rt_101",
  "check_in": "2026-07-01",
  "check_out": "2026-07-05",
  "guests": 2,
  "payment_method_id": "pm_456"
}

Response

{
  "booking_id": "b_789",
  "status": "CONFIRMED",
  "total_price": 960,
  "confirmation_code": "NYC-ABC-789"
}

Cancel Booking

POST /v1/bookings/{booking_id}/cancel
Idempotency-Key: cancel_req_123

Response

{
  "booking_id": "b_789",
  "status": "CANCELLED",
  "refund_status": "PROCESSING"
}

Modify Booking

PATCH /v1/bookings/{booking_id}
Idempotency-Key: modify_req_123

Request

{
  "new_check_in": "2026-07-02",
  "new_check_out": "2026-07-06",
  "room_type_id": "rt_101"
}

Submit Review

POST /v1/hotels/{hotel_id}/reviews

Request

{
  "booking_id": "b_789",
  "user_id": "u_123",
  "rating": 5,
  "comment": "Great stay and excellent location."
}

Host Creates / Updates Property

POST /v1/hosts/{host_id}/hotels
PATCH /v1/hosts/{host_id}/hotels/{hotel_id}
POST /v1/hosts/{host_id}/hotels/{hotel_id}/room-types
PATCH /v1/hosts/{host_id}/room-types/{room_type_id}/inventory

High-Level Design

Core Services

1. API Gateway

Responsibilities:

Authentication
TLS termination
Request routing
Rate limiting
Idempotency-key validation
Request logging

2. User Service

Responsibilities:

User profile
Authentication metadata
Loyalty status
User preferences

3. Hotel Service

Responsibilities:

Hotel metadata
Room types
Amenities
Host property management

4. Search Service

Responsibilities:

Full-text and geo search
Filtering by price, amenities, ratings
Sorting and pagination
Uses Elasticsearch / OpenSearch

5. Availability Service

Responsibilities:

Real-time room availability
Inventory lookup
Temporary reservation holds
Prevent double-booking

6. Booking Service

Responsibilities:

Booking lifecycle
Reservation state machine
Booking modification
Cancellation
Orchestration with payment and inventory

7. Payment Service

Responsibilities:

Payment authorization
Capture
Refund
Idempotent payment requests
Integration with external payment providers

8. Review Service

Responsibilities:

Review submission
Rating aggregation
Eligibility validation based on completed booking

9. Recommendation Service

Responsibilities:

Personalized hotel recommendations
Ranking based on user behavior, location, price, ratings, and availability

10. Notification Service

Responsibilities:

Confirmation emails
SMS notifications
Cancellation notices
Payment receipts

Storage

Primary Databases

Data Storage Reason
Users	Relational DB	Strong identity consistency
Hotels	Relational DB	Structured property data
Room inventory	Relational DB / distributed SQL	Strong consistency
Bookings	Relational DB / distributed SQL	Transactional correctness
Payments	Relational DB	Auditability and idempotency
Reviews	NoSQL or relational DB	High write/read scale
Search index	Elasticsearch / OpenSearch	Fast filtering and geo search
Cache	Redis / Memcached	Low-latency hot reads
Events	Kafka / Pulsar	Async workflows

Booking State Machine

INITIATED
  -> INVENTORY_HELD
  -> PAYMENT_AUTHORIZED
  -> CONFIRMED
Failure states:
-> PAYMENT_FAILED
-> HOLD_EXPIRED
-> CANCELLED
-> REFUNDED

High-Level Booking Flow

User searches hotels.
Search Service queries search index.
User selects hotel and checks availability.
Availability Service checks room inventory.
User submits booking request with idempotency key.
Booking Service creates booking in PENDING state.
Availability Service places temporary inventory hold.
Payment Service authorizes payment.
Booking Service confirms booking.
Inventory hold is converted into confirmed reservation.
Notification event is published.
Notification Service sends confirmation.

Detailed Component Design

5.1 Search Service

Responsibilities

Search hotels by location, dates, price, amenities, and ratings.
Support pagination and ranking.
Return candidate hotels quickly.

Data Source

Search Service uses OpenSearch / Elasticsearch.

Indexed fields:

{
  "hotel_id": "h_123",
  "name": "Central Park Hotel",
  "location": {
    "lat": 40.785,
    "lon": -73.968
  },
  "city": "New York",
  "amenities": ["wifi", "pool", "gym"],
  "rating": 4.6,
  "price_bucket": "200-300",
  "host_id": "host_123"
}

Availability-Aware Search

The search index should not be the source of truth for availability.

Recommended approach:

Search index returns candidate hotels.
Search Service calls Availability Service for requested dates.
Unavailable hotels are filtered out or deprioritized.
Availability hints can be cached briefly, for example 30 to 120 seconds.

This balances performance and correctness.

Performance Optimizations

Cache popular searches:
- location + date_range + guests + filters
Use geo-partitioned indexes.
Use pagination with opaque page tokens.
Use denormalized hotel search documents.
Update search index asynchronously from hotel events.

Tradeoff

Search results may briefly show stale availability, but final booking is protected by the strongly consistent Availability Service.

5.2 Availability Service

This is the most correctness-sensitive part of the system.

Inventory Model

Instead of storing every physical room as a row for every date, store inventory by:

hotel_id
room_type_id
date
total_inventory
reserved_count
held_count

Example:

CREATE TABLE room_inventory (
  hotel_id BIGINT,
  room_type_id BIGINT,
  stay_date DATE,
  total_inventory INT,
  reserved_count INT,
  held_count INT,
  version BIGINT,
  PRIMARY KEY (hotel_id, room_type_id, stay_date)
);

A booking from July 1 to July 5 consumes inventory for:

Checkout date is not consumed.

5.3 Preventing Double-Booking

For each requested date, Availability Service performs an atomic conditional update.

UPDATE room_inventory
SET held_count = held_count + 1,
    version = version + 1
WHERE hotel_id = :hotel_id
  AND room_type_id = :room_type_id
  AND stay_date = :stay_date
  AND total_inventory - reserved_count - held_count > 0;

The hold succeeds only if every date in the requested range is updated successfully.

If any date fails:

Roll back previously held dates.
Return no availability.
Booking remains unconfirmed.

For high-scale systems, this can be implemented using:

Distributed SQL transactions, such as Spanner, CockroachDB, or YugabyteDB.
Single-shard transactional relational DB if inventory is partitioned by hotel.
Redis Lua script for temporary holds plus durable DB confirmation, though the DB should remain the source of truth.

5.4 Temporary Holds

When a user starts booking, the system creates a short-lived inventory hold.

hold_id
user_id
hotel_id
room_type_id
date_range
expires_at
status

Typical TTL:

5 to 10 minutes

If payment is not completed before expiration:

Hold expires.
Inventory is released.
Booking becomes HOLD_EXPIRED.

This prevents a user from locking inventory indefinitely.

5.5 Booking Service

Responsibilities

Own booking lifecycle.
Coordinate inventory and payment.
Maintain booking state machine.
Ensure idempotency.

Booking Table

CREATE TABLE bookings (
  booking_id BIGINT PRIMARY KEY,
  user_id BIGINT,
  hotel_id BIGINT,
  room_type_id BIGINT,
  check_in DATE,
  check_out DATE,
  guests INT,
  status VARCHAR(32),
  total_price DECIMAL,
  idempotency_key VARCHAR(128),
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  UNIQUE(user_id, idempotency_key)
);

Booking Flow

Receive booking request
Check idempotency key
Create booking with PENDING status
Request inventory hold
Authorize payment
Convert hold to confirmed reservation
Mark booking CONFIRMED
Publish BookingConfirmed event
Send notification asynchronously

Failure Handling

Failure Handling
Inventory hold fails	Mark booking as FAILED / SOLD_OUT
Payment authorization fails	Release hold, mark PAYMENT_FAILED
Payment succeeds but DB update fails	Retry booking confirmation using idempotent recovery job
Notification fails	Retry through queue; booking remains confirmed
Service crashes mid-flow	Resume using booking state machine

5.6 Payment Service

Responsibilities

Integrate with payment providers.
Store payment attempts.
Support authorization, capture, refund.
Handle provider callbacks / webhooks.

Payment Idempotency

Payment requests must include idempotency keys.

payment_idempotency_key = booking_id + payment_attempt_number

Payment table:

CREATE TABLE payments (
  payment_id BIGINT PRIMARY KEY,
  booking_id BIGINT,
  provider_payment_id VARCHAR(128),
  amount DECIMAL,
  currency VARCHAR(8),
  status VARCHAR(32),
  idempotency_key VARCHAR(128),
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  UNIQUE(idempotency_key)
);

Payment Flow

Booking Service asks Payment Service to authorize payment.
Payment Service checks local idempotency table.
Payment Service calls external provider.
Provider returns authorization result.
Payment Service stores result.
Booking Service confirms or fails booking.

External Payment Resilience

Use:

Circuit breaker
Timeout
Retry with exponential backoff
Idempotency key
Webhook reconciliation
Dead-letter queue for unresolved payment events

5.7 Cancellation Flow

Cancellation is also idempotent.

User sends cancel request with idempotency key
Booking Service verifies booking is cancellable
Booking status changes to CANCELLATION_PENDING
Inventory is released
Refund is initiated
Booking status changes to CANCELLED
Notification event is published

Cancellation Policy

Cancellation policy can depend on:

Hotel rules
Rate type
Time before check-in
Local regulations
Non-refundable pricing

5.8 Modification Flow

Modification is equivalent to a mini rebooking.

Safe approach:

Check availability for new dates.
Place hold for new dates.
Calculate price difference.
Authorize additional payment or initiate partial refund.
Release old inventory.
Confirm new booking details.

Important:

Do not release old inventory before successfully holding new inventory.
Use a state machine:
- MODIFICATION_PENDING
- MODIFICATION_CONFIRMED
- MODIFICATION_FAILED

5.9 Review Service

Requirements

Only users with completed stays can review.
One review per completed booking.
Reviews can be moderated.

Review Table

CREATE TABLE reviews (
  review_id BIGINT PRIMARY KEY,
  hotel_id BIGINT,
  booking_id BIGINT,
  user_id BIGINT,
  rating INT,
  comment TEXT,
  status VARCHAR(32),
  created_at TIMESTAMP,
  UNIQUE(booking_id)
);

Aggregation

Rating aggregates can be updated asynchronously:

ReviewCreated event -> Aggregation Worker -> hotel_rating_summary

This avoids expensive aggregation queries on the hot path.

5.10 Host / Hotel Manager Service

Hosts can:

Create hotels.
Add room types.
Set inventory.
Set pricing.
Block dates.
Update amenities.
View bookings.

Host Update Propagation

When a host updates a property:

Hotel DB update -> HotelUpdated event -> Search Index update

Search index updates are eventually consistent.

5.11 Personalized Recommendations

Recommendation signals:

Search history
Booking history
Wishlist behavior
Price preference
Location preference
Review ratings
Similar users
Real-time availability

Recommendation can be served by:

Offline batch ranking
Online re-ranking
Feature store
Embedding-based retrieval

For interview scope:

Start with rule-based ranking.
Add ML ranking later.

5.12 Rate Limiting

Rate limiting protects the platform from abuse and traffic spikes.

API Gateway Limits

Example limits:

Search: 60 requests / minute / user
Availability check: 30 requests / minute / user
Booking creation: 5 requests / minute / user
Review creation: 10 requests / hour / user
Host inventory updates: 100 requests / minute / host

Implementation

Use Redis token bucket:

key = rate_limit:{user_id}:{api_name}

If exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Additional Protection

IP-level limits for anonymous users.
CAPTCHA for suspicious behavior.
Bot detection for scraping.
Separate stricter limits for payment and booking APIs.

5.13 Idempotency Handling

Idempotency is required for:

Create booking
Payment authorization
Payment capture
Cancellation
Modification
Refund

Idempotency Table

CREATE TABLE idempotency_keys (
  idempotency_key VARCHAR(128),
  user_id BIGINT,
  request_hash VARCHAR(256),
  response_body JSON,
  status_code INT,
  created_at TIMESTAMP,
  PRIMARY KEY (user_id, idempotency_key)
);

Behavior

When duplicate request arrives:

If key is new, process request.
If key exists and request hash matches, return saved response.
If key exists and request hash differs, return 409 Conflict.

This handles client retries safely.

5.14 Thundering Herd Scenario

Scenario

A popular hotel has only one room left during a major event. Thousands of users try to book it at the same time.

Risks

Inventory DB overload
Lock contention
Payment provider overload
Poor user experience
Duplicate booking attempts

Mitigations

1. Atomic Conditional Inventory Update

Only one request can successfully hold the final room.

2. Request Coalescing

For availability checks, identical requests can be coalesced:

hotel_id + room_type_id + date_range

Multiple users share the same cached availability result for a very short TTL.

3. Short TTL Availability Cache

Use a 1 to 5 second cache for hot availability reads.

Important:

Cache is used for display only.
Booking still goes through strong inventory check.

4. Queue-Based Admission Control

For extreme contention:

Place booking attempts into a per-hotel or per-room-type queue.
Process limited concurrent attempts.
Return fast failure when inventory is gone.

5. Rate Limit Booking Attempts

Limit repeated booking attempts per user and IP.

6. Load Shedding

When downstream systems are overloaded:

Reject non-critical requests.
Preserve booking and payment capacity.
Return graceful errors.

5.15 Caching Strategy

Cacheable Data

Data Cache TTL
Hotel details	5 to 30 minutes
Hotel photos	CDN
Reviews summary	5 to 15 minutes
Search results	30 to 120 seconds
Availability hints	1 to 120 seconds
User recommendations	5 to 30 minutes

Not Fully Cacheable

Final booking inventory check
Payment state
Booking confirmation state

5.16 Data Partitioning

Hotel Metadata

Partition by:

hotel_id

Inventory

Partition by:

hotel_id or region + hotel_id

This keeps inventory updates for a hotel localized.

Bookings

Partition by:

user_id or booking_id

For hotel manager views, maintain secondary index by:

hotel_id + check_in_date

Reviews

Partition by:

hotel_id

This supports fast hotel review lookup.

5.17 Event-Driven Architecture

Important events:

HotelCreated
HotelUpdated
InventoryUpdated
BookingCreated
BookingConfirmed
BookingCancelled
PaymentAuthorized
PaymentFailed
ReviewCreated

Consumers:

Search indexer
Notification worker
Recommendation pipeline
Analytics pipeline
Fraud detection
Host dashboard updater

Use Kafka / Pulsar with:

At-least-once delivery
Idempotent consumers
Dead-letter queues
Event schema versioning

5.18 Observability

Metrics

Track:

Search latency p50 / p95 / p99
Booking success rate
Booking failure reason
Inventory hold failure rate
Payment authorization latency
Payment failure rate
Double-booking incidents
Cache hit ratio
Queue lag
API rate limit count
5xx error rate
DB lock contention
Inventory transaction latency

Logs

Use structured logs:

{
  "request_id": "req_123",
  "user_id": "u_123",
  "booking_id": "b_789",
  "hotel_id": "h_123",
  "status": "PAYMENT_AUTHORIZED"
}

Tracing

Distributed tracing across:

API Gateway -> Booking Service -> Availability Service -> Payment Service -> Notification Service

5.19 Security

Payment Security

Do not store raw card data.
Use tokenized payment methods.
Use PCI-compliant payment provider.
Encrypt payment metadata at rest.

User Security

OAuth / session authentication.
Role-based access control:
- traveler
- host
- admin
Hosts can only modify their own properties.

Data Security

TLS everywhere.
Encryption at rest.
Audit logs for booking, payment, and host inventory changes.
Fraud detection on suspicious booking/payment patterns.

5.20 Availability and Disaster Recovery

Multi-AZ Deployment

Deploy services across multiple availability zones.

Database Replication

Primary with synchronous replica for critical booking data.
Read replicas for hotel metadata and review reads.

Backups

Point-in-time recovery for booking and payment DBs.
Regular snapshot backups.

Degraded Mode

If Recommendation Service is down:

Return popular hotels.

If Review Service is down:

Hide review submission temporarily.
Continue booking flow.

If Search Index is stale:

Continue serving cached results.
Final availability still validated at booking.

If Notification Service is down:

Booking remains confirmed.
Notification retries later.

If Payment Provider is down:

Use secondary provider if configured.
Otherwise fail gracefully before confirming booking.

5.21 Key Tradeoffs

Strong Consistency vs Availability

Inventory booking requires strong consistency. During a partition, the system should reject bookings rather than risk double-booking.

Search Freshness vs Performance

Search index is eventually consistent. This is acceptable because final booking validates availability.

Synchronous vs Asynchronous Work

Keep booking confirmation synchronous for user confidence.

Move non-critical work async:

Notifications
Analytics
Search indexing
Recommendations
Review aggregation

Room-Level vs Room-Type-Level Inventory

Room-type-level inventory is simpler and scalable.

Room-level assignment can happen closer to check-in.

5.22 Final Architecture Summary

The system uses a read-optimized search architecture combined with a strongly consistent booking and inventory core.

Search is fast and scalable using OpenSearch, cache, and denormalized hotel documents.
Booking correctness is protected by atomic inventory holds and transactional booking state.
Payments are secure and idempotent.
Reviews, notifications, recommendations, and search indexing are asynchronous.
The system handles high traffic using caching, partitioning, rate limiting, queues, and load shedding.
Edge cases such as thundering herd, retries, duplicate requests, and rate limiting are explicitly handled.

Requirements

Functional Requirements:

Allow users to search and filter hotels by location, dates, price, and amenities.
Allow users to book a hotel room for specific dates.
Display real-time room availability and prevent double-booking.
Support secure payment processing for reservations.
Allow users to manage bookings including cancellation and modification.
Allow users to leave reviews and ratings for hotels.
Allow hosts or hotel managers to list and manage properties.

Non-Functional Requirements:

Availability

Search and hotel browsing should be highly available.
Booking flow should prioritize correctness over availability.
Target:
- Search API: 99.99% availability
- Booking API: 99.95% availability
- Payment flow: 99.9% availability with retry-safe behavior

Scalability

Support millions of users, hotels, reviews, and bookings.
Read-heavy traffic pattern:
- Search, hotel detail, recommendations dominate traffic.
Booking traffic is lower volume but requires strong consistency.

Performance

Target latency:

Search hotels: p95 < 500 ms
Hotel detail page: p95 < 300 ms
Availability check: p95 < 200 ms
Booking confirmation: p95 < 2 seconds, excluding external payment latency
Review submission: p95 < 300 ms

Reliability

Booking must not double-book rooms.
Payments must be idempotent.
Booking confirmation must eventually be delivered even if notification service fails.

Resilience

Use circuit breakers around payment providers.
Use retries with exponential backoff for transient failures.
Use queues for asynchronous workflows such as emails, receipts, search indexing, and recommendations.

Fault Tolerance

Replicate databases across availability zones.
Use read replicas for search-heavy metadata reads.
Use message queues with dead-letter queues.
Use idempotency keys for booking, payment, and cancellation APIs.

Consistency

Strong consistency required for room inventory reservation.
Eventual consistency acceptable for:
- Search index
- Reviews aggregation
- Recommendations
- Analytics
- Hotel listing updates appearing in search

API Design

User Search Hotels

GET /v1/hotels/search

Query Parameters

{
  "location": "New York",
  "check_in": "2026-07-01",
  "check_out": "2026-07-05",
  "guests": 2,
  "min_price": 100,
  "max_price": 500,
  "amenities": ["wifi", "pool"],
  "sort": "price_asc",
  "page_token": "abc123"
}

Response

{
  "hotels": [
    {
      "hotel_id": "h_123",
      "name": "Central Park Hotel",
      "location": "New York",
      "rating": 4.6,
      "starting_price": 240,
      "available": true,
      "amenities": ["wifi", "gym", "pool"]
    }
  ],
  "next_page_token": "def456"
}

Get Hotel Details

GET /v1/hotels/{hotel_id}

Response

{
  "hotel_id": "h_123",
  "name": "Central Park Hotel",
  "description": "Luxury hotel near Central Park",
  "rooms": [
    {
      "room_type_id": "rt_101",
      "name": "Deluxe King",
      "base_price": 240,
      "capacity": 2,
      "amenities": ["wifi", "city_view"]
    }
  ],
  "reviews_summary": {
    "rating": 4.6,
    "review_count": 1832
  }
}

Check Availability

GET /v1/hotels/{hotel_id}/availability

Query Parameters

{
  "check_in": "2026-07-01",
  "check_out": "2026-07-05",
  "guests": 2
}

Response

{
  "hotel_id": "h_123",
  "available_rooms": [
    {
      "room_type_id": "rt_101",
      "available_count": 3,
      "nightly_price": 240,
      "total_price": 960
    }
  ]
}

Create Booking

POST /v1/bookings
Idempotency-Key: booking_req_abc123

Request

{
  "user_id": "u_123",
  "hotel_id": "h_123",
  "room_type_id": "rt_101",
  "check_in": "2026-07-01",
  "check_out": "2026-07-05",
  "guests": 2,
  "payment_method_id": "pm_456"
}

Response

{
  "booking_id": "b_789",
  "status": "CONFIRMED",
  "total_price": 960,
  "confirmation_code": "NYC-ABC-789"
}

Cancel Booking

POST /v1/bookings/{booking_id}/cancel
Idempotency-Key: cancel_req_123

Response

{
  "booking_id": "b_789",
  "status": "CANCELLED",
  "refund_status": "PROCESSING"
}

Modify Booking

PATCH /v1/bookings/{booking_id}
Idempotency-Key: modify_req_123

Request

{
  "new_check_in": "2026-07-02",
  "new_check_out": "2026-07-06",
  "room_type_id": "rt_101"
}

Submit Review

POST /v1/hotels/{hotel_id}/reviews

Request

{
  "booking_id": "b_789",
  "user_id": "u_123",
  "rating": 5,
  "comment": "Great stay and excellent location."
}

Host Creates / Updates Property

POST /v1/hosts/{host_id}/hotels
PATCH /v1/hosts/{host_id}/hotels/{hotel_id}
POST /v1/hosts/{host_id}/hotels/{hotel_id}/room-types
PATCH /v1/hosts/{host_id}/room-types/{room_type_id}/inventory

High-Level Design

Core Services

1. API Gateway

Responsibilities:

Authentication
TLS termination
Request routing
Rate limiting
Idempotency-key validation
Request logging

2. User Service

Responsibilities:

User profile
Authentication metadata
Loyalty status
User preferences

3. Hotel Service

Responsibilities:

Hotel metadata
Room types
Amenities
Host property management

4. Search Service

Responsibilities:

Full-text and geo search
Filtering by price, amenities, ratings
Sorting and pagination
Uses Elasticsearch / OpenSearch

5. Availability Service

Responsibilities:

Real-time room availability
Inventory lookup
Temporary reservation holds
Prevent double-booking

6. Booking Service

Responsibilities:

Booking lifecycle
Reservation state machine
Booking modification
Cancellation
Orchestration with payment and inventory

7. Payment Service

Responsibilities:

Payment authorization
Capture
Refund
Idempotent payment requests
Integration with external payment providers

8. Review Service

Responsibilities:

Review submission
Rating aggregation
Eligibility validation based on completed booking

9. Recommendation Service

Responsibilities:

Personalized hotel recommendations
Ranking based on user behavior, location, price, ratings, and availability

10. Notification Service

Responsibilities:

Confirmation emails
SMS notifications
Cancellation notices
Payment receipts

Storage

Primary Databases

Data Storage Reason
Users	Relational DB	Strong identity consistency
Hotels	Relational DB	Structured property data
Room inventory	Relational DB / distributed SQL	Strong consistency
Bookings	Relational DB / distributed SQL	Transactional correctness
Payments	Relational DB	Auditability and idempotency
Reviews	NoSQL or relational DB	High write/read scale
Search index	Elasticsearch / OpenSearch	Fast filtering and geo search
Cache	Redis / Memcached	Low-latency hot reads
Events	Kafka / Pulsar	Async workflows

Booking State Machine

INITIATED
  -> INVENTORY_HELD
  -> PAYMENT_AUTHORIZED
  -> CONFIRMED
Failure states:
-> PAYMENT_FAILED
-> HOLD_EXPIRED
-> CANCELLED
-> REFUNDED

High-Level Booking Flow

User searches hotels.
Search Service queries search index.
User selects hotel and checks availability.
Availability Service checks room inventory.
User submits booking request with idempotency key.
Booking Service creates booking in PENDING state.
Availability Service places temporary inventory hold.
Payment Service authorizes payment.
Booking Service confirms booking.
Inventory hold is converted into confirmed reservation.
Notification event is published.
Notification Service sends confirmation.

Detailed Component Design

5.1 Search Service

Responsibilities

Search hotels by location, dates, price, amenities, and ratings.
Support pagination and ranking.
Return candidate hotels quickly.

Data Source

Search Service uses OpenSearch / Elasticsearch.

Indexed fields:

{
  "hotel_id": "h_123",
  "name": "Central Park Hotel",
  "location": {
    "lat": 40.785,
    "lon": -73.968
  },
  "city": "New York",
  "amenities": ["wifi", "pool", "gym"],
  "rating": 4.6,
  "price_bucket": "200-300",
  "host_id": "host_123"
}

Availability-Aware Search

The search index should not be the source of truth for availability.

Recommended approach:

Search index returns candidate hotels.
Search Service calls Availability Service for requested dates.
Unavailable hotels are filtered out or deprioritized.
Availability hints can be cached briefly, for example 30 to 120 seconds.

This balances performance and correctness.

Performance Optimizations

Cache popular searches:
- location + date_range + guests + filters
Use geo-partitioned indexes.
Use pagination with opaque page tokens.
Use denormalized hotel search documents.
Update search index asynchronously from hotel events.

Tradeoff

Search results may briefly show stale availability, but final booking is protected by the strongly consistent Availability Service.

5.2 Availability Service

This is the most correctness-sensitive part of the system.

Inventory Model

Instead of storing every physical room as a row for every date, store inventory by:

hotel_id
room_type_id
date
total_inventory
reserved_count
held_count

Example:

CREATE TABLE room_inventory (
  hotel_id BIGINT,
  room_type_id BIGINT,
  stay_date DATE,
  total_inventory INT,
  reserved_count INT,
  held_count INT,
  version BIGINT,
  PRIMARY KEY (hotel_id, room_type_id, stay_date)
);

A booking from July 1 to July 5 consumes inventory for:

Checkout date is not consumed.

5.3 Preventing Double-Booking

For each requested date, Availability Service performs an atomic conditional update.

UPDATE room_inventory
SET held_count = held_count + 1,
    version = version + 1
WHERE hotel_id = :hotel_id
  AND room_type_id = :room_type_id
  AND stay_date = :stay_date
  AND total_inventory - reserved_count - held_count > 0;

The hold succeeds only if every date in the requested range is updated successfully.

If any date fails:

Roll back previously held dates.
Return no availability.
Booking remains unconfirmed.

For high-scale systems, this can be implemented using:

Distributed SQL transactions, such as Spanner, CockroachDB, or YugabyteDB.
Single-shard transactional relational DB if inventory is partitioned by hotel.
Redis Lua script for temporary holds plus durable DB confirmation, though the DB should remain the source of truth.

5.4 Temporary Holds

When a user starts booking, the system creates a short-lived inventory hold.

hold_id
user_id
hotel_id
room_type_id
date_range
expires_at
status

Typical TTL:

5 to 10 minutes

If payment is not completed before expiration:

Hold expires.
Inventory is released.
Booking becomes HOLD_EXPIRED.

This prevents a user from locking inventory indefinitely.

5.5 Booking Service

Responsibilities

Own booking lifecycle.
Coordinate inventory and payment.
Maintain booking state machine.
Ensure idempotency.

Booking Table

CREATE TABLE bookings (
  booking_id BIGINT PRIMARY KEY,
  user_id BIGINT,
  hotel_id BIGINT,
  room_type_id BIGINT,
  check_in DATE,
  check_out DATE,
  guests INT,
  status VARCHAR(32),
  total_price DECIMAL,
  idempotency_key VARCHAR(128),
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  UNIQUE(user_id, idempotency_key)
);

Booking Flow

Receive booking request
Check idempotency key
Create booking with PENDING status
Request inventory hold
Authorize payment
Convert hold to confirmed reservation
Mark booking CONFIRMED
Publish BookingConfirmed event
Send notification asynchronously

Failure Handling

Failure Handling
Inventory hold fails	Mark booking as FAILED / SOLD_OUT
Payment authorization fails	Release hold, mark PAYMENT_FAILED
Payment succeeds but DB update fails	Retry booking confirmation using idempotent recovery job
Notification fails	Retry through queue; booking remains confirmed
Service crashes mid-flow	Resume using booking state machine

5.6 Payment Service

Responsibilities

Integrate with payment providers.
Store payment attempts.
Support authorization, capture, refund.
Handle provider callbacks / webhooks.

Payment Idempotency

Payment requests must include idempotency keys.

payment_idempotency_key = booking_id + payment_attempt_number

Payment table:

CREATE TABLE payments (
  payment_id BIGINT PRIMARY KEY,
  booking_id BIGINT,
  provider_payment_id VARCHAR(128),
  amount DECIMAL,
  currency VARCHAR(8),
  status VARCHAR(32),
  idempotency_key VARCHAR(128),
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  UNIQUE(idempotency_key)
);

Payment Flow

Booking Service asks Payment Service to authorize payment.
Payment Service checks local idempotency table.
Payment Service calls external provider.
Provider returns authorization result.
Payment Service stores result.
Booking Service confirms or fails booking.

External Payment Resilience

Use:

Circuit breaker
Timeout
Retry with exponential backoff
Idempotency key
Webhook reconciliation
Dead-letter queue for unresolved payment events

5.7 Cancellation Flow

Cancellation is also idempotent.

User sends cancel request with idempotency key
Booking Service verifies booking is cancellable
Booking status changes to CANCELLATION_PENDING
Inventory is released
Refund is initiated
Booking status changes to CANCELLED
Notification event is published

Cancellation Policy

Cancellation policy can depend on:

Hotel rules
Rate type
Time before check-in
Local regulations
Non-refundable pricing

5.8 Modification Flow

Modification is equivalent to a mini rebooking.

Safe approach:

Check availability for new dates.
Place hold for new dates.
Calculate price difference.
Authorize additional payment or initiate partial refund.
Release old inventory.
Confirm new booking details.

Important:

Do not release old inventory before successfully holding new inventory.
Use a state machine:
- MODIFICATION_PENDING
- MODIFICATION_CONFIRMED
- MODIFICATION_FAILED

5.9 Review Service

Requirements

Only users with completed stays can review.
One review per completed booking.
Reviews can be moderated.

Review Table

CREATE TABLE reviews (
  review_id BIGINT PRIMARY KEY,
  hotel_id BIGINT,
  booking_id BIGINT,
  user_id BIGINT,
  rating INT,
  comment TEXT,
  status VARCHAR(32),
  created_at TIMESTAMP,
  UNIQUE(booking_id)
);

Aggregation

Rating aggregates can be updated asynchronously:

ReviewCreated event -> Aggregation Worker -> hotel_rating_summary

This avoids expensive aggregation queries on the hot path.

5.10 Host / Hotel Manager Service

Hosts can:

Create hotels.
Add room types.
Set inventory.
Set pricing.
Block dates.
Update amenities.
View bookings.

Host Update Propagation

When a host updates a property:

Hotel DB update -> HotelUpdated event -> Search Index update

Search index updates are eventually consistent.

5.11 Personalized Recommendations

Recommendation signals:

Search history
Booking history
Wishlist behavior
Price preference
Location preference
Review ratings
Similar users
Real-time availability

Recommendation can be served by:

Offline batch ranking
Online re-ranking
Feature store
Embedding-based retrieval

For interview scope:

Start with rule-based ranking.
Add ML ranking later.

5.12 Rate Limiting

Rate limiting protects the platform from abuse and traffic spikes.

API Gateway Limits

Example limits:

Search: 60 requests / minute / user
Availability check: 30 requests / minute / user
Booking creation: 5 requests / minute / user
Review creation: 10 requests / hour / user
Host inventory updates: 100 requests / minute / host

Implementation

Use Redis token bucket:

key = rate_limit:{user_id}:{api_name}

If exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Additional Protection

IP-level limits for anonymous users.
CAPTCHA for suspicious behavior.
Bot detection for scraping.
Separate stricter limits for payment and booking APIs.

5.13 Idempotency Handling

Idempotency is required for:

Create booking
Payment authorization
Payment capture
Cancellation
Modification
Refund

Idempotency Table

CREATE TABLE idempotency_keys (
  idempotency_key VARCHAR(128),
  user_id BIGINT,
  request_hash VARCHAR(256),
  response_body JSON,
  status_code INT,
  created_at TIMESTAMP,
  PRIMARY KEY (user_id, idempotency_key)
);

Behavior

When duplicate request arrives:

If key is new, process request.
If key exists and request hash matches, return saved response.
If key exists and request hash differs, return 409 Conflict.

This handles client retries safely.

5.14 Thundering Herd Scenario

Scenario

A popular hotel has only one room left during a major event. Thousands of users try to book it at the same time.

Risks

Inventory DB overload
Lock contention
Payment provider overload
Poor user experience
Duplicate booking attempts

Mitigations

1. Atomic Conditional Inventory Update

Only one request can successfully hold the final room.

2. Request Coalescing

For availability checks, identical requests can be coalesced:

hotel_id + room_type_id + date_range

Multiple users share the same cached availability result for a very short TTL.

3. Short TTL Availability Cache

Use a 1 to 5 second cache for hot availability reads.

Important:

Cache is used for display only.
Booking still goes through strong inventory check.

4. Queue-Based Admission Control

For extreme contention:

Place booking attempts into a per-hotel or per-room-type queue.
Process limited concurrent attempts.
Return fast failure when inventory is gone.

5. Rate Limit Booking Attempts

Limit repeated booking attempts per user and IP.

6. Load Shedding

When downstream systems are overloaded:

Reject non-critical requests.
Preserve booking and payment capacity.
Return graceful errors.

5.15 Caching Strategy

Cacheable Data

Data Cache TTL
Hotel details	5 to 30 minutes
Hotel photos	CDN
Reviews summary	5 to 15 minutes
Search results	30 to 120 seconds
Availability hints	1 to 120 seconds
User recommendations	5 to 30 minutes

Not Fully Cacheable

Final booking inventory check
Payment state
Booking confirmation state

5.16 Data Partitioning

Hotel Metadata

Partition by:

hotel_id

Inventory

Partition by:

hotel_id or region + hotel_id

This keeps inventory updates for a hotel localized.

Bookings

Partition by:

user_id or booking_id

For hotel manager views, maintain secondary index by:

hotel_id + check_in_date

Reviews

Partition by:

hotel_id

This supports fast hotel review lookup.

5.17 Event-Driven Architecture

Important events:

HotelCreated
HotelUpdated
InventoryUpdated
BookingCreated
BookingConfirmed
BookingCancelled
PaymentAuthorized
PaymentFailed
ReviewCreated

Consumers:

Search indexer
Notification worker
Recommendation pipeline
Analytics pipeline
Fraud detection
Host dashboard updater

Use Kafka / Pulsar with:

At-least-once delivery
Idempotent consumers
Dead-letter queues
Event schema versioning

5.18 Observability

Metrics

Track:

Search latency p50 / p95 / p99
Booking success rate
Booking failure reason
Inventory hold failure rate
Payment authorization latency
Payment failure rate
Double-booking incidents
Cache hit ratio
Queue lag
API rate limit count
5xx error rate
DB lock contention
Inventory transaction latency

Logs

Use structured logs:

{
  "request_id": "req_123",
  "user_id": "u_123",
  "booking_id": "b_789",
  "hotel_id": "h_123",
  "status": "PAYMENT_AUTHORIZED"
}

Tracing

Distributed tracing across:

API Gateway -> Booking Service -> Availability Service -> Payment Service -> Notification Service

5.19 Security

Payment Security

Do not store raw card data.
Use tokenized payment methods.
Use PCI-compliant payment provider.
Encrypt payment metadata at rest.

User Security

OAuth / session authentication.
Role-based access control:
- traveler
- host
- admin
Hosts can only modify their own properties.

Data Security

TLS everywhere.
Encryption at rest.
Audit logs for booking, payment, and host inventory changes.
Fraud detection on suspicious booking/payment patterns.

5.20 Availability and Disaster Recovery

Multi-AZ Deployment

Deploy services across multiple availability zones.

Database Replication

Primary with synchronous replica for critical booking data.
Read replicas for hotel metadata and review reads.

Backups

Point-in-time recovery for booking and payment DBs.
Regular snapshot backups.

Degraded Mode

If Recommendation Service is down:

Return popular hotels.

If Review Service is down:

Hide review submission temporarily.
Continue booking flow.

If Search Index is stale:

Continue serving cached results.
Final availability still validated at booking.

If Notification Service is down:

Booking remains confirmed.
Notification retries later.

If Payment Provider is down:

Use secondary provider if configured.
Otherwise fail gracefully before confirming booking.

5.21 Key Tradeoffs

Strong Consistency vs Availability

Inventory booking requires strong consistency. During a partition, the system should reject bookings rather than risk double-booking.

Search Freshness vs Performance

Search index is eventually consistent. This is acceptable because final booking validates availability.

Synchronous vs Asynchronous Work

Keep booking confirmation synchronous for user confidence.

Move non-critical work async:

Notifications
Analytics
Search indexing
Recommendations
Review aggregation

Room-Level vs Room-Type-Level Inventory

Room-type-level inventory is simpler and scalable.

Room-level assignment can happen closer to check-in.

5.22 Final Architecture Summary

The system uses a read-optimized search architecture combined with a strongly consistent booking and inventory core.

Search is fast and scalable using OpenSearch, cache, and denormalized hotel documents.
Booking correctness is protected by atomic inventory holds and transactional booking state.
Payments are secure and idempotent.
Reviews, notifications, recommendations, and search indexing are asynchronous.
The system handles high traffic using caching, partitioning, rate limiting, queues, and load shedding.
Edge cases such as thundering herd, retries, duplicate requests, and rate limiting are explicitly handled.