FrontDesk Module Documentation

Overview

The FrontDesk module is the operational heart of the OLOW Hotel ERP system. It manages the complete guest journey from reservation to checkout, including room management, bookings, folios (guest ledgers), check-in/check-out processes, and integration with all other hotel systems.

Key Features

Reservations & Bookings: Complete booking lifecycle management
Room Management: Room types, rates, availability tracking
Check-In/Check-Out: Streamlined guest arrival and departure workflows
Folios: Guest billing ledgers with charges and payments
Group Bookings: Manage multiple reservations together
Rate Management: Dynamic pricing, rate plans, seasonal rates
Room Blocks: Reserve rooms for events or groups
Guest Profiles: Preferences, notes, loyalty programs
Revenue Management: Occupancy-based pricing optimization
Loyalty Programs: Points-based rewards system

Architecture

Domain Layer (`app/Domain/FrontDesk`)

Models (27 Models)

Core Booking Models

Booking (Booking.php)

Central reservation record
Table: bookings
Key Fields:
- booking_number: Unique booking reference
- customer_id: Guest making reservation
- check_in_date, check_out_date: Stay dates
- status: CONFIRMED | CHECKED_IN | CHECKED_OUT | CANCELLED | NO_SHOW | EXPIRED
- source: WALK_IN | WEBSITE | PHONE | OTA
- total_adults, total_children: Guest count
- booking_group_id: For group reservations (nullable)
- use_master_folio: Group billing flag
Relationships:
- customer(): Guest
- rooms(): BookingRoom records
- folio(): Guest billing ledger
- bookingGroup(): Group if part of group booking
Computed Attributes:
- total_amount: Sum of folio charges
- total_paid: Sum of payments
- balance_due: Amount outstanding
- stay_nights: Number of nights
- is_group_booking: Boolean
Traits: BelongsToProperty, SoftDeletes

BookingRoom (BookingRoom.php)

Pivot table linking bookings to rooms
Table: booking_rooms
Key Fields:
- booking_id: Parent booking
- room_type_id: Requested room type
- room_id: Assigned physical room (nullable until check-in)
- room_rate_plan_id: Rate plan used
- nightly_rate: Locked-in rate
- adults, children: Occupancy
- booked_as_room_type_id: Original room type if upgraded
Relationships:
- booking(): Parent booking
- roomType(): Requested type
- room(): Assigned room
- ratePlan(): Rate plan

Room Models

Room (Room.php)

Physical room inventory
Table: rooms
Key Fields:
- room_number: Unique room identifier
- room_type_id: Room category
- floor: Floor number
- status: CLEAN | DIRTY | INSPECTED | OUT_OF_ORDER | MAINTENANCE
- is_active: Active flag
Relationships:
- type(): RoomType
- bookingRooms(): Current and future bookings
- housekeepingAssignment(): Assigned housekeeper
- housekeepingTasks(): Cleaning tasks
- maintenanceIssues(): Maintenance tickets
- activeBlocks(): Room blocks
Scopes:
- scopeAvailable($startDate, $endDate): Available rooms for period
Computed Attributes:
- assigned_staff: Current housekeeper
- is_blocked: Has active block
Traits: BelongsToProperty

RoomType (RoomType.php)

Room categories (Standard, Deluxe, Suite, etc.)
Table: room_types
Key Fields:
- name: Type name
- description: Full description
- base_occupancy: Standard guest count
- max_occupancy: Maximum guests
- base_rate: Default nightly rate
- sort_order: Display order
Relationships:
- rooms(): Physical rooms of this type
- images(): Room type photos
- amenities(): Features (many-to-many)
- rates(): Rate plans
Traits: BelongsToProperty

RoomRate (RoomRate.php)

Dated pricing for room types
Table: room_rates
Key Fields:
- room_type_id: Room category
- rate_date: Specific date
- rate: Price for that date
- occupancy_1_rate, occupancy_2_rate, etc.: Per-guest pricing
Traits: BelongsToProperty

RoomRatePlan (RoomRatePlan.php)

Named rate plans (Standard, Corporate, AAA, etc.)
Table: room_rate_plans
Key Fields:
- name: Plan name
- code: Short code
- discount_type: PERCENTAGE | FIXED
- discount_value: Discount amount
- is_public: Visible to guests
Traits: BelongsToProperty

Folio Models (Guest Billing)

Folio (Folio.php)

Guest billing ledger
Table: folios
Key Fields:
- booking_id: Associated booking
- customer_id: Bill-to party
- status: OPEN | CLOSED | VOID
- notes: Billing notes
Relationships:
- booking(): Parent booking
- customer(): Bill-to party
- lines(): Charges
- payments(): Payments
Computed Attributes:
- total_charges: Sum of charges
- total_payments: Sum of payments
- balance: Amount due
Traits: BelongsToProperty

FolioLine (FolioLine.php)

Individual charges
Table: folio_lines
Key Fields:
- folio_id: Parent folio
- trans_date: Transaction date
- type: ROOM | TAX | SERVICE | POS | GYM | HALL | MINIBAR | LAUNDRY | ADJUSTMENT | DISCOUNT
- description: Charge description
- amount: Amount (negative for discounts)
- revenue_account_id: GL account mapping
- relatable_type, relatable_id: Source record (polymorphic)
- is_voided: Void flag
- voided_by, voided_at, void_reason: Void tracking
Relationships:
- folio(): Parent folio
- revenueAccount(): GL account
- relatable(): Source (BookingRoom, PosOrder, etc.)

FolioPayment (FolioPayment.php)

Guest payments
Table: folio_payments
Key Fields:
- folio_id: Parent folio
- trans_date: Payment date
- amount: Payment amount (negative for refunds)
- method: CASH | CARD | BANK | MOBILE | WALLET | DEPOSIT_APPLICATION
- reference: Transaction reference
- cash_account_id: GL account (Added via 2026_01_27 migration)
- is_refund: Refund flag
- original_payment_id: If refund, original payment
- is_deposit: True if advance deposit
- is_deposit_application: True if applying deposit to balance
Relationships:
- folio(): Parent folio
- cashAccount(): GL cash account

Advanced Features

BookingGroup (BookingGroup.php)

Group reservations
Table: booking_groups
Key Fields:
- group_name: Group identifier
- organization: Company/organization
- total_rooms: Room count
- master_folio_id: Consolidated billing
- billing_contact, billing_email: Billing info
Relationships:
- bookings(): Individual bookings
- masterFolio(): Group billing folio
Traits: BelongsToProperty

RoomBlock (RoomBlock.php)

Reserved room inventory
Table: room_blocks
Key Fields:
- block_name: Block identifier
- room_type_id: Room category
- quantity: Number of rooms
- start_date, end_date: Block period
- rate: Special rate (nullable)
- is_active: Active flag
- released_at: Release date
Scopes:
- scopeActive(): Active blocks
- scopeOverlapping($start, $end): Blocks in period
Traits: BelongsToProperty

LoyaltyAccount (LoyaltyAccount.php)

Guest loyalty program accounts
Table: loyalty_accounts
Key Fields:
- customer_id: Guest
- tier_id: Loyalty tier
- points_balance: Current points
- lifetime_points: Total earned
- member_since: Join date
Relationships:
- customer(): Guest
- tier(): Loyalty tier
- transactions(): Point transactions
Traits: BelongsToProperty

GuestPreference (GuestPreference.php)

Guest preferences and special requests
Table: guest_preferences
Key Fields:
- customer_id: Guest
- preference_type: ROOM_TYPE | FLOOR | BED_TYPE | AMENITIES | DIETARY | OTHER
- preference_value: Preference details
- notes: Additional notes
Traits: BelongsToProperty

PricingRule (PricingRule.php)

Dynamic pricing rules
Table: pricing_rules
Key Fields:
- rule_name: Rule identifier
- room_type_id: Applicable room type (nullable for all)
- condition_type: OCCUPANCY | DAY_OF_WEEK | SEASON | BOOKING_WINDOW
- condition_value: Condition details (JSON)
- adjustment_type: PERCENTAGE | FIXED
- adjustment_value: Price adjustment
- priority: Rule priority
- is_active: Active flag
Traits: BelongsToProperty

Services (19 Services)

BookingService (`BookingService.php`)

Purpose: Core booking lifecycle management

Dependencies:

FolioService
InvoiceService
ReceiptService
SmsService
AccountingPoster
GuestJourneyService
RevenueManagementService

Key Methods:

`createReservation(array $data): Booking`

Creates a new reservation

php

$booking = $bookingService->createReservation([
    'customer_id' => $customer->id,
    'check_in_date' => '2026-02-01',
    'check_out_date' => '2026-02-05',
    'total_adults' => 2,
    'total_children' => 0,
    'rooms' => [
        [
            'room_type_id' => $roomType->id,
            'adults' => 2,
            'nightly_rate' => 150.00,
            'room_rate_plan_id' => $ratePlan->id,
        ]
    ],
    'source' => 'WEBSITE',
    'notes' => 'Anniversary celebration',
]);

Process:

Validates availability
Creates booking record
Creates booking_rooms records
Creates folio
Sends confirmation SMS
Returns booking

`assignRoom(BookingRoom $bookingRoom, Room $room): void`

Assigns physical room to booking

Features:

Pessimistic locking to prevent race conditions
Updates room status
Logs activity

`checkIn(Booking $booking): void`

Processes guest check-in

Process:

Validates booking status
Ensures rooms assigned
Adds room charges to folio (if not already added)
Changes status to CHECKED_IN
Updates room status to OCCUPIED
Sends welcome SMS
Logs activity

`checkOut(Booking $booking): void`

Processes guest checkout

Process:

Finalizes all charges
Calculates final balance
Checks balance paid (throws if outstanding)
Generates AR invoice
Closes folio
Changes status to CHECKED_OUT
Updates room status to DIRTY
Logs activity
Processes loyalty points

`transitionStatus(Booking $booking, BookingStatusEnum $newStatus, ?string $notes = null): void`

State machine for booking statuses

Valid Transitions:

CONFIRMED → CHECKED_IN
CONFIRMED → CANCELLED
CONFIRMED → NO_SHOW
CHECKED_IN → CHECKED_OUT

FolioService (`FolioService.php`)

Purpose: Guest billing ledger management

Dependencies:

AccountingPoster
TaxEngine
SmsService

Key Methods:

`createFolioForBooking($booking): Folio`

Creates folio for new booking

`addCharge(Folio $folio, string $type, string $description, float $amount, ...): FolioLine`

Adds charge to guest ledger

php

$folioService->addCharge(
    folio: $folio,
    type: 'ROOM',
    description: 'Deluxe Room - Night 1',
    amount: 150.00,
    revenueAccountId: $roomRevenueAccount->id,
    relatable: $bookingRoom,
    applyTax: true
);

Process:

Creates folio line
Calculates tax (if applicable)
Creates tax folio line
Posts to accounting (debit AR, credit Revenue)
Sends SMS notification (if configured)

`addPayment(Folio $folio, string $method, float $amount, ...): FolioPayment`

Records guest payment

Process:

Creates folio payment record
Posts to accounting (debit Cash, credit AR)
Updates folio balance

`applyDiscount(Folio $folio, string $type, float $amount, string $reason, ...): FolioLine`

Applies discount to folio

Types:

PERCENTAGE: Percentage off total
FIXED: Fixed amount off

Creates: Negative folio line

`voidCharge(FolioLine $line, string $reason, ...): void`

Voids a folio charge

Process:

Marks original line as voided
Creates reversal line
Reverses accounting entry
Logs activity

`recordDeposit(Folio $folio, string $method, float $amount, ...): FolioPayment`

Records advance deposit

Accounting:

Debit: Cash
Credit: Customer Deposits (Liability)

`applyDepositsToBalance(Folio $folio): void`

Applies deposits at checkout

Accounting:

Debit: Customer Deposits
Credit: Accounts Receivable

AvailabilityService (`AvailabilityService.php`)

Purpose: Room availability checking

Key Methods:

`checkAvailability(RoomType $roomType, Carbon $checkIn, Carbon $checkOut, int $quantity = 1): bool`

Checks if rooms available

Considers:

Existing bookings
Room blocks
Out of order rooms
Maintenance status

`getAvailableRoomTypes(Carbon $checkIn, Carbon $checkOut): Collection`

Returns all available room types for period

RateService (`RateService.php`)

Purpose: Rate calculation and management

Key Methods:

`calculateRate(RoomType $roomType, Carbon $date, int $occupancy, ...): float`

Calculates rate for specific date

Considers:

Base room rate
Seasonal rates
Pricing rules (occupancy-based, day-of-week, etc.)
Rate plan discounts

`getRateForPeriod(RoomType $roomType, Carbon $checkIn, Carbon $checkOut, ...): float`

Calculates total for date range

RevenueManagementService (`RevenueManagementService.php`)

Purpose: Dynamic pricing optimization

Key Methods:

`calculateOptimalRate(RoomType $roomType, Carbon $date): float`

Recommends rate based on occupancy forecasts

Factors:

Current occupancy
Historical occupancy
Forward bookings
Competitor rates (if integrated)
Demand patterns

BookingCancellationService (`BookingCancellationService.php`)

Purpose: Handles booking cancellations

Key Methods:

`cancel(Booking $booking, string $reason, bool $applyPenalty = false): void`

Cancels a booking

Process:

Validates cancellation allowed
Calculates cancellation penalty (if applicable)
Processes refunds
Voids folio charges
Updates booking status
Releases rooms
Sends cancellation email/SMS

Additional Services

BookingDateChangeService: Modify reservation dates
RoomChangeService: Move guest to different room
BookingMergeService: Merge multiple bookings
GroupBookingService: Manage group reservations
RoomBlockService: Manage room blocks
LoyaltyService: Loyalty points and rewards
GuestProfileService: Guest preference management
GuestJourneyService: Track guest interactions
EarlyLateCheckService: Early check-in/late checkout
BookingInvoicePdfService: Generate invoices

Database Schema

Core Tables

mermaid

erDiagram
    BOOKING ||--o{ BOOKING_ROOM : contains
    BOOKING ||--|| FOLIO : "has ledger"
    BOOKING }o--|| CUSTOMER : "booked by"
    BOOKING }o--o| BOOKING_GROUP : "belongs to"

    BOOKING_ROOM }o--|| ROOM_TYPE : "requests"
    BOOKING_ROOM }o--o| ROOM : "assigned to"
    BOOKING_ROOM }o--o| ROOM_RATE_PLAN : "uses plan"

    ROOM }o--|| ROOM_TYPE : "is type"
    ROOM_TYPE ||--o{ ROOM_RATE : "has rates"

    FOLIO ||--o{ FOLIO_LINE : "has charges"
    FOLIO ||--o{ FOLIO_PAYMENT : "has payments"

    FOLIO_LINE }o--o| ACCOUNTING_ACCOUNT : "posts to"

Integration with Other Modules

Accounting Integration

Every folio transaction posts to the general ledger:

Room Charge:

php

// When charge added to folio
Debit: Accounts Receivable (Guest)
Credit: Room Revenue
Credit: Tax Payable (if applicable)

Guest Payment:

php

// When payment received
Debit: Cash / Bank
Credit: Accounts Receivable (Guest)

Checkout & Invoice:

php

// At checkout, folio becomes AR invoice
// Invoice automatically created from folio
// Already posted to GL via folio charges/payments

Housekeeping Integration

Room status synchronized
Cleaning tasks auto-created on checkout
Room ready notifications

Maintenance Integration

Out of order rooms excluded from availability
Maintenance tickets linked to rooms

SMS Integration

Booking confirmations
Pre-arrival messages
Folio charge notifications
Checkout summaries

Loyalty Integration

Points earned on checkout
Tier-based benefits
Automatic upgrades

Common Workflows

1. Create a Reservation

User: Front Desk Staff

Navigate to FrontDesk > Reservations
Click + New Reservation
Select guest (or create new guest)
Enter check-in and check-out dates
Select room type and quantity
Review rate calculation
Add any special requests or notes
Confirm reservation
System creates booking and folio
Confirmation sent to guest

2. Check-In a Guest

User: Front Desk Staff

Navigate to FrontDesk > Check-In
Find booking (by confirmation #, name, or date)
Verify guest information
Assign physical room(s) if not pre-assigned
Collect payment or authorize card
Review room charges
Complete check-in
Print room keys/cards
Room status changes to OCCUPIED

3. Add Charges to Stay

User: Various Staff

Via Folio:

Open booking > View Folio
Click + Add Charge
Select charge type (SERVICE, MINIBAR, etc.)
Enter amount and description
Save charge
Charge posts to GL immediately

Via Integrated Modules:

POS charges auto-post to folio
Gym day pass charges auto-post
Hall event charges auto-post

4. Check-Out a Guest

User: Front Desk Staff

Navigate to booking
Click Check Out
Review final folio
Process final payment if balance due
System:
- Closes folio
- Generates AR invoice
- Changes booking status
- Sets room to DIRTY
- Sends receipt email/SMS
- Awards loyalty points
Print receipt

5. Handle Group Booking

User: Front Desk Manager

Navigate to FrontDesk > Group Bookings
Click + New Group
Enter group details (name, organization, contact)
Add individual reservations
Choose billing method:
- Individual Folios: Each guest pays separately
- Master Folio: Group pays together
Save group
Individual bookings created
Master folio created (if selected)

Configuration

Room Types Setup

Navigate to FrontDesk > Room Types
Create categories (Standard, Deluxe, Suite, etc.)
Set base occupancy and max occupancy
Set base rate
Upload photos
Assign amenities

Rate Plans Setup

Navigate to FrontDesk > Rate Plans
Create plans (Standard, Corporate, AAA, Government, etc.)
Set discount type and value
Set public visibility
Assign to room types

Seasonal Rates

Navigate to FrontDesk > Rate Management
Select date range
Override rates for specific dates
System uses override rates in calculations

Known Issues (from Audit)

Issues Found

MAJOR

MAJ-FD-001: Folio Payment Missing cash_account_id Field

Location: folio_payments table
Status: [FIXED]
Description: Added cash_account_id field via migration 2026_01_27_000001.
Priority: P1

MAJ-FD-002: Missing Deposit Tracking Fields

Location: folio_payments table
Status: [FIXED]
Description: Added is_deposit, is_deposit_application, original_payment_id via migration 2026_01_27_000001.
Priority: P1

MINOR

MIN-FD-001: Booking Status ENUM Limitation

Location: Booking migration, uses string instead of enum
Description: Status stored as string, no database-level constraint
Impact: Potential for invalid status values
Fix: Consider using ENUM or CHECK constraint
Priority: P3

MIN-FD-002: Missing folio_type Field

Location: folios table
Description: No way to distinguish guest folios from master folios
Impact: Querying group vs individual folios requires joins
Fix: Add folio_type enum field
Priority: P3

Best Practices

For Developers

Always use services: Don't create bookings/folios directly
Use transactions: Booking creation is multi-step
Check availability: Before confirming bookings
Log activities: Use BookingActivity for audit trail
Send notifications: Use SmsService for guest communications

For Users

Assign rooms early: Better housekeeping planning
Review folios: Before checkout
Document discounts: Always include reason
Void vs delete: Void charges, never delete
Use rate plans: For consistent pricing

Module Status: Production Last Reviewed: January 26, 2026 Documentation Version: 1.0

FrontDesk Module Documentation ​

Overview ​

Key Features ​

Architecture ​

Domain Layer (app/Domain/FrontDesk) ​

Models (27 Models) ​

Core Booking Models ​

Room Models ​

Folio Models (Guest Billing) ​

Advanced Features ​

Services (19 Services) ​

BookingService (BookingService.php) ​

createReservation(array $data): Booking ​

assignRoom(BookingRoom $bookingRoom, Room $room): void ​

checkIn(Booking $booking): void ​

checkOut(Booking $booking): void ​

transitionStatus(Booking $booking, BookingStatusEnum $newStatus, ?string $notes = null): void ​

FolioService (FolioService.php) ​

createFolioForBooking($booking): Folio ​

addCharge(Folio $folio, string $type, string $description, float $amount, ...): FolioLine ​

addPayment(Folio $folio, string $method, float $amount, ...): FolioPayment ​

applyDiscount(Folio $folio, string $type, float $amount, string $reason, ...): FolioLine ​

voidCharge(FolioLine $line, string $reason, ...): void ​

recordDeposit(Folio $folio, string $method, float $amount, ...): FolioPayment ​

applyDepositsToBalance(Folio $folio): void ​

AvailabilityService (AvailabilityService.php) ​

checkAvailability(RoomType $roomType, Carbon $checkIn, Carbon $checkOut, int $quantity = 1): bool ​

getAvailableRoomTypes(Carbon $checkIn, Carbon $checkOut): Collection ​

RateService (RateService.php) ​

calculateRate(RoomType $roomType, Carbon $date, int $occupancy, ...): float ​

getRateForPeriod(RoomType $roomType, Carbon $checkIn, Carbon $checkOut, ...): float ​

RevenueManagementService (RevenueManagementService.php) ​

calculateOptimalRate(RoomType $roomType, Carbon $date): float ​

BookingCancellationService (BookingCancellationService.php) ​

cancel(Booking $booking, string $reason, bool $applyPenalty = false): void ​

Additional Services ​

Database Schema ​

Core Tables ​

Integration with Other Modules ​

Accounting Integration ​

Housekeeping Integration ​

Maintenance Integration ​

SMS Integration ​

Loyalty Integration ​

Common Workflows ​

1. Create a Reservation ​

2. Check-In a Guest ​

3. Add Charges to Stay ​

4. Check-Out a Guest ​

5. Handle Group Booking ​

Configuration ​

Room Types Setup ​

Rate Plans Setup ​

Seasonal Rates ​

Known Issues (from Audit) ​

Issues Found ​

MAJOR ​

MINOR ​

Best Practices ​

For Developers ​

For Users ​

FrontDesk Module Documentation

Overview

Key Features

Architecture

Domain Layer (`app/Domain/FrontDesk`)

Models (27 Models)

Core Booking Models

Room Models

Folio Models (Guest Billing)

Advanced Features

Services (19 Services)

BookingService (`BookingService.php`)

`createReservation(array $data): Booking`

`assignRoom(BookingRoom $bookingRoom, Room $room): void`

`checkIn(Booking $booking): void`

`checkOut(Booking $booking): void`

`transitionStatus(Booking $booking, BookingStatusEnum $newStatus, ?string $notes = null): void`

FolioService (`FolioService.php`)

`createFolioForBooking($booking): Folio`

`addCharge(Folio $folio, string $type, string $description, float $amount, ...): FolioLine`

`addPayment(Folio $folio, string $method, float $amount, ...): FolioPayment`

`applyDiscount(Folio $folio, string $type, float $amount, string $reason, ...): FolioLine`

`voidCharge(FolioLine $line, string $reason, ...): void`

`recordDeposit(Folio $folio, string $method, float $amount, ...): FolioPayment`

`applyDepositsToBalance(Folio $folio): void`

AvailabilityService (`AvailabilityService.php`)

`checkAvailability(RoomType $roomType, Carbon $checkIn, Carbon $checkOut, int $quantity = 1): bool`

`getAvailableRoomTypes(Carbon $checkIn, Carbon $checkOut): Collection`

RateService (`RateService.php`)

`calculateRate(RoomType $roomType, Carbon $date, int $occupancy, ...): float`

`getRateForPeriod(RoomType $roomType, Carbon $checkIn, Carbon $checkOut, ...): float`

RevenueManagementService (`RevenueManagementService.php`)

`calculateOptimalRate(RoomType $roomType, Carbon $date): float`

BookingCancellationService (`BookingCancellationService.php`)

`cancel(Booking $booking, string $reason, bool $applyPenalty = false): void`

Additional Services

Database Schema

Core Tables

Integration with Other Modules

Accounting Integration

Housekeeping Integration

Maintenance Integration

SMS Integration

Loyalty Integration

Common Workflows

1. Create a Reservation

2. Check-In a Guest

3. Add Charges to Stay

4. Check-Out a Guest

5. Handle Group Booking

Configuration

Room Types Setup

Rate Plans Setup

Seasonal Rates

Known Issues (from Audit)

Issues Found

MAJOR

MINOR

Best Practices

For Developers

For Users