# Direct Booking Engine Architecture

The Calian direct booking engine converts website visitors into guaranteed direct hotel reservations while strictly preventing inventory overbooking.

---

## 1. Inventory & Availability Algorithm

### 1.1 Physical Inventory Calculation
The availability for any given `RoomType` between `CheckIn` and `CheckOut` is calculated via:

$$\text{Available Rooms} = \text{Total Active Physical Rooms} - (\text{Active Reservations} + \text{Active Temporary Holds} + \text{Out of Order Rooms})$$

1. **Active Physical Rooms:** Count of rooms assigned to `RoomType` where `operational_status != 'Out of Order'`.
2. **Active Reservations:** Count of bookings intersecting the requested date range where status in (`Confirmed`, `Guaranteed`, `Checked In`).
3. **Active Temporary Holds:** Short-lived 15-minute locks created when a user enters Step 4/5 of the checkout funnel to prevent concurrent double-booking.

---

## 2. Booking Funnel Journey

```text
[ Step 1: Availability Search ]
   Select: Dates, Adults, Children, Promo Code
                │
                ▼
[ Step 2: Available Room Types ]
   Shows real-time rates, room specs, cancellation policy, inclusions
                │
                ▼
[ Step 3: Rate Plan Selection ]
   Best Available Rate, Bed & Breakfast (+ Breakfast buffet), Non-refundable (10% off)
                │
                ▼
[ Step 4: Add-On Upsells ]
   Airport Pickup (Entebbe -> Mbuya), Couples Spa Package, Romantic In-Room Setup, Late Checkout
                │
                ▼
[ Step 5: Guest Details & Special Requests ]
   Name, Email, WhatsApp Phone, Country, ETA, Dietary/Room requests
   *Creates temporary 15-minute inventory hold*
                │
                ▼
[ Step 6: Payment & Guarantee ]
   Option A: Pesapal 3.0 Online (Mobile Money / Visa / Mastercard)
   Option B: Guarantee / Pay at Hotel (Subject to cancellation policy)
                │
                ▼
[ Step 7: Instant Confirmation & Voucher ]
   Unique Booking Code (e.g. CAL-20260826-7812), downloadable branded PDF voucher & calendar invite
```

---

## 3. Concurrency & Race-Condition Prevention
- Database transactions with `lockForUpdate()` wrap room allocation operations.
- Temporary hold tokens with a 15-minute TTL guarantee that two users attempting to checkout the last available Deluxe Suite cannot both be charged.