Lodging Marketplace Booking Architecture

Scope and evidence boundary

This is a reference lodging-marketplace design informed by public Airbnb materials and general payment/database primitives. It is not a claim that the diagram reproduces Airbnb's current private service graph. Public Airbnb documentation shows that payment behavior depends on payment method, geography, and schedule: a reservation request can place an authorization or charge, acceptance can convert an authorization to a charge, and a decline can remove a hold or require a refund. Some reservations support split or later payments. The design therefore avoids the false universal story “charge immediately, keep funds in an Airbnb wallet, and refund only in bookkeeping.”

Core invariants

1. Search availability is a stale projection. The booking database is the only authority that can allocate a stay-night.
2. Every night has a single allocation boundary. A concrete implementation can enforce UNIQUE(listing_id, stay_date) on active allocation rows, or an equivalent PostgreSQL range exclusion constraint.
3. A hold carries an opaque token, state, expiry and monotonic version. Confirm, release and expiry are conditional transitions. A delayed worker cannot release a hold that a newer payment transition already confirmed.
4. The database transaction writes reservation state and an outbox record together. Consumers are idempotent by event id and aggregate version.
5. No transaction spans the booking database and an external payment provider. Provider operations have stable idempotency keys; verified webhooks and reconciliation converge the saga.
6. Money uses integer minor units plus currency and exponent. A double-entry ledger appends balanced entries linked to the provider operation; history is never overwritten.
7. The quote snapshots cancellation, fee, tax and payout policy versions. Later policy edits do not retroactively rewrite a signed booking.

[CASE]hotel-booking