Design Airbnb: A Production-Grade System Architecture for Booking at Scale

// io.thecodeforge — System Design tutorial

// Service boundaries and communication

// Search Service: read-optimized, uses Elasticsearch
// - Handles listing queries, filters, pagination
// - Data synced from Booking Service via CDC (Debezium)

// Booking Service: write-optimized, uses PostgreSQL
// - Handles booking creation, cancellation, availability
// - Uses optimistic locking with version column

// Payment Service: async, uses Kafka + Stripe
// - Processes payments via queue
// - Idempotency keys prevent duplicate charges

// User Service: CRUD, uses PostgreSQL
// - Manages user profiles, authentication
// - Caches sessions in Redis

// Communication:
// - Synchronous: gRPC for low-latency internal calls (e.g., Booking -> Payment for idempotency check)
// - Asynchronous: Kafka for events (e.g., BookingCreated -> Search to update index)

// API Gateway: routes requests, handles auth, rate limiting

// io.thecodeforge — System Design tutorial

// CDC pipeline: PostgreSQL -> Debezium -> Kafka -> Elasticsearch

// 1. Debezium connector monitors booking_db.public.bookings table
// 2. On INSERT/UPDATE, emits event to Kafka topic 'booking_events'
// 3. Search service consumes topic, updates Elasticsearch index

// Example event (JSON):
// {
//   "op": "c", // create
//   "after": {
//     "id": 12345,
//     "property_id": 678,
//     "start_date": "2025-06-01",
//     "end_date": "2025-06-05",
//     "status": "confirmed"
//   }
// }

// Elasticsearch update logic (pseudo):
// function handleBookingCreated(event) {
//   const propertyId = event.after.property_id;
//   // Mark dates as booked in the property's availability index
//   esClient.update({
//     index: 'properties',
//     id: propertyId,
//     body: {
//       script: {
//         source: "ctx._source.booked_dates.addAll(params.dates)",
//         params: { dates: generateDateRange(event.after.start_date, event.after.end_date) }
//       }
//     }
//   });
// }

// io.thecodeforge — System Design tutorial

// PostgreSQL booking creation with optimistic locking

-- Table: property_calendar
-- Columns: property_id, date, is_available, version

BEGIN;

-- Read current availability and version
SELECT is_available, version
INTO v_available, v_version
FROM property_calendar
WHERE property_id = 123 AND date BETWEEN '2025-06-01' AND '2025-06-05'
FOR UPDATE; -- pessimistic lock for high contention

IF NOT v_available THEN
    ROLLBACK;
    RAISE EXCEPTION 'Property not available';
END IF;

-- Update availability with version check
UPDATE property_calendar
SET is_available = false, version = version + 1
WHERE property_id = 123
  AND date BETWEEN '2025-06-01' AND '2025-06-05'
  AND version = v_version; -- optimistic check

IF NOT FOUND THEN
    ROLLBACK;
    RAISE EXCEPTION 'Concurrency conflict, retry';
END IF;

-- Insert booking record
INSERT INTO bookings (property_id, guest_id, start_date, end_date, status)
VALUES (123, 456, '2025-06-01', '2025-06-05', 'confirmed');

COMMIT;

// io.thecodeforge — System Design tutorial

// Booking service: after successful DB insert, enqueue payment event

// Kafka producer (Java)
producer.send(new ProducerRecord<>("payment_events", bookingId, 
    new PaymentEvent(bookingId, guestId, amount, idempotencyKey)));

// Payment service consumer (Java)
@KafkaListener(topics = "payment_events")
public void handlePayment(PaymentEvent event) {
    // Check if already processed (idempotency)
    if (paymentRepository.existsByIdempotencyKey(event.getIdempotencyKey())) {
        return; // already processed
    }
    
    try {
        // Charge via Stripe with idempotency key
        Charge charge = stripe.charges.create(
            new ChargeCreateParams()
                .setAmount(event.getAmount())
                .setCurrency("usd")
                .setSource("tok_visa")
                .setIdempotencyKey(event.getIdempotencyKey())
        );
        
        // Update booking status to 'confirmed'
        bookingService.updateStatus(event.getBookingId(), "confirmed");
        
        // Store idempotency key
        paymentRepository.save(new PaymentRecord(event.getIdempotencyKey(), charge.getId()));
    } catch (StripeException e) {
        // Payment failed, cancel booking and restore availability
        bookingService.cancelBooking(event.getBookingId());
        // Optionally notify user
    }
}

// io.thecodeforge — System Design tutorial

// Cache-aside for property details

function getPropertyDetails(propertyId) {
    // Try cache first
    String cached = redis.get("property:" + propertyId);
    if (cached != null) {
        return JSON.parse(cached);
    }
    
    // Cache miss, load from DB
    Property property = db.query("SELECT * FROM properties WHERE id = ?", propertyId);
    if (property == null) {
        return null;
    }
    
    // Populate cache with TTL
    redis.setex("property:" + propertyId, 300, JSON.stringify(property)); // 5 min TTL
    
    return property;
}

// io.thecodeforge — System Design tutorial

-- PostgreSQL schema

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE properties (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    host_id UUID REFERENCES users(id),
    title VARCHAR(255) NOT NULL,
    description TEXT,
    price_per_night DECIMAL(10,2) NOT NULL,
    max_guests INT,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE property_calendar (
    property_id UUID REFERENCES properties(id),
    date DATE NOT NULL,
    is_available BOOLEAN DEFAULT true,
    price DECIMAL(10,2), -- can override base price
    version INT DEFAULT 1,
    PRIMARY KEY (property_id, date)
);

CREATE INDEX idx_calendar_property_date ON property_calendar(property_id, date);

CREATE TABLE bookings (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    property_id UUID REFERENCES properties(id),
    guest_id UUID REFERENCES users(id),
    start_date DATE NOT NULL,
    end_date DATE NOT NULL,
    status VARCHAR(20) DEFAULT 'pending', -- pending, confirmed, cancelled
    total_price DECIMAL(10,2),
    created_at TIMESTAMP DEFAULT NOW(),
    CONSTRAINT no_overlap EXCLUDE USING gist (
        property_id WITH =,
        daterange(start_date, end_date, '[]') WITH &&
    ) WHERE (status = 'confirmed')
);

CREATE TABLE payments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    booking_id UUID REFERENCES bookings(id),
    amount DECIMAL(10,2) NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    stripe_charge_id VARCHAR(255),
    idempotency_key VARCHAR(255) UNIQUE,
    created_at TIMESTAMP DEFAULT NOW()
);

// io.thecodeforge — System Design tutorial

// Example API endpoints

// Search properties
GET /v1/properties?lat=40.7128&lng=-74.0060&checkin=2025-06-01&checkout=2025-06-05&guests=2&page=1&per_page=20

// Response:
{
  "data": [
    {
      "id": "uuid",
      "title": "Cozy Apartment",
      "price_per_night": 150.00,
      "avg_rating": 4.5,
      "images": ["url1", "url2"]
    }
  ],
  "pagination": {
    "cursor": "next_page_token",
    "has_more": true
  }
}

// Create booking
POST /v1/bookings
{
  "property_id": "uuid",
  "start_date": "2025-06-01",
  "end_date": "2025-06-05",
  "guests": 2,
  "idempotency_key": "unique-key-123"
}

// Response:
{
  "booking_id": "uuid",
  "status": "pending",
  "total_price": 600.00
}

// Process payment (async)
POST /v1/payments
{
  "booking_id": "uuid",
  "payment_method_id": "pm_123",
  "idempotency_key": "unique-key-456"
}

// Response:
{
  "payment_id": "uuid",
  "status": "processing"
}

// io.thecodeforge — System Design tutorial

// Database configuration with read replicas

// Primary: handles writes (INSERT, UPDATE, DELETE)
// Replicas: handle reads (SELECT)

// Connection pool configuration (HikariCP example)
// Primary datasource
HikariConfig primaryConfig = new HikariConfig();
primaryConfig.setJdbcUrl("jdbc:postgresql://primary-host:5432/airbnb");
primaryConfig.setMaximumPoolSize(50);

// Replica datasource
HikariConfig replicaConfig = new HikariConfig();
replicaConfig.setJdbcUrl("jdbc:postgresql://replica-host:5432/airbnb");
replicaConfig.setMaximumPoolSize(200); // more connections for reads

// Use @Transactional(readOnly = true) for read-only methods
// Spring will route to replica datasource automatically if configured

// io.thecodeforge — System Design tutorial

// Prometheus metrics (example)

// Booking success rate
metric_booking_success_total{status="success"} 1000
metric_booking_success_total{status="failure"} 2

// Payment queue depth
metric_payment_queue_depth 150

// Search latency p99
metric_search_latency_seconds{quantile="0.99"} 0.180

// Alert rules (Prometheus)
- alert: HighBookingFailureRate
  expr: rate(metric_booking_success_total{status="failure"}[5m]) / rate(metric_booking_success_total[5m]) > 0.01
  for: 1m
  annotations:
    summary: "Booking failure rate above 1%"

- alert: PaymentQueueGrowing
  expr: metric_payment_queue_depth > 1000
  for: 2m
  annotations:
    summary: "Payment queue depth > 1000"