primitives booking

Booking

Bookings power 360 Stays, the short-stay module. A booking reserves a property for a date range with a guest count and a priced breakdown. Bookings are distinct from visits (which are walk-throughs, not overnight stays) and from leases (which are long-term tenancy contracts).

Active contributors: Saksham, Ravi

Model

File: app/models/bookings.py

The Booking table captures the full lifecycle of a short-stay reservation. Key columns:

• booking_reference - human-readable unique identifier shown to guests and hosts
• user_id, property_id - foreign keys with ON DELETE CASCADE
• check_in_date, check_out_date, nights, guests - the stay window
• Price breakdown: base_amount, taxes_amount, service_charges, discount_amount, total_amount - all Numeric(10, 2) for currency precision
• booking_status - BookingStatus enum (pending, confirmed, checked_in, checked_out, cancelled, completed)
• payment_status - PaymentStatus enum (pending, partial, paid, refunded, failed)
• primary_guest_name, primary_guest_phone, primary_guest_email - denormalized guest contact, since a booking may be made by a user on behalf of someone else
• guest_details - JSON blob for additional guests
• actual_check_in, actual_check_out - timestamps set when the guest physically arrives and leaves
• early_check_in, late_check_out - boolean flags for flexibility requests
• cancellation_date, cancellation_reason, refund_amount - cancellation audit trail
• guest_rating, guest_review, host_rating, host_review - two-way review system

The overlapping bookings rule

This is a deliberate business rule and a common source of confusion. The same property can be booked by multiple people for the same or overlapping dates. There are no double-booking guards, no date-overlap conflict checks, and no DB exclusion constraints on bookings.

check_availability in app/services/booking.py only validates that the property exists and that the guest count fits max_occupancy. It does not check for conflicting bookings. This matches the platform's model: hosts manually confirm or decline each pending booking, and overlapping requests are treated as competing leads rather than conflicts.

See background/pitfalls.md for why this matters and what not to "fix".

Lifecycle

A booking moves through pending -> confirmed -> checked_in -> checked_out -> completed, with cancelled reachable from any pre-check-in state. Payment status evolves independently: a booking can be confirmed while payment_status is still partial. Refunds set payment_status = refunded and populate refund_amount.

REST and MCP surfaces

The /api/v1/bookings router covers create, list, get, cancel, check availability, and pricing. The user MCP server exposes bookings_create, bookings_list, bookings_get, bookings_cancel, bookings_check_availability, and bookings_get_pricing tools.