Task 9 — Hotel and Reservation Network

Objective

Create a hotel and reservation management system for a network of hotels.

The system manages:

• hotel properties
• rooms
• room types
• guests
• reservations
• reservation rooms
• availability
• seasonal pricing
• promotions
• payments
• check-in
• check-out
• hotel services
• housekeeping
• room maintenance
• employees
• invoices
• cancellations
• no-shows
• occupancy
• operational history

The implementation must manage the complete reservation lifecycle while ensuring that rooms are never assigned to conflicting reservations.

The system must preserve both:

commercial state

such as reservations, prices, payments, and invoices, and:

operational state

such as room occupancy, housekeeping, maintenance, and guest stays.

Hotel Network

Create a network containing at least five hotels.

For example:

        HT01 — London Central
        HT02 — Paris Riverside
        HT03 — Rome Plaza
        HT04 — Belgrade Grand
        HT05 — Dubai Marina

Hotels may have different:

• room inventories
• room types
• prices
• services
• policies
• employees
• maintenance schedules

Hotel

Each hotel contains:

• ID
• Name
• City
• Country
• Timezone
• Check-In Time
• Check-Out Time
• Cancellation Policy

A possible model is:

type Hotel struct {
    ID                 string
    Name               string
    City               string
    Country            string
    Timezone           string
    CheckInTime        string
    CheckOutTime       string
    CancellationPolicyID string
}

Room Type

Rooms are classified by type. Examples:

• single
• double
• twin
• deluxe
• suite
• family

A room type contains:

• ID
• Name
• Maximum Guests
• Maximum Adults
• Maximum Children
• Base Price Per Night

For example:

type RoomType struct {
    ID              string
    Name            string
    MaxGuests       int
    MaxAdults       int
    MaxChildren     int
    BasePrice       float64
}

Room

Each room belongs to one hotel and one room type. A possible model is:

type Room struct {
    ID         string
    HotelID    string
    RoomTypeID string
    Number     string
    Floor      int
    Status     RoomStatus
}

Possible room states:

• available
• occupied
• dirty
• cleaning
• maintenance
• out_of_service

Reservation availability and operational room status are related but are not the same concept.

A room may have no reservation conflict and still be unavailable because it is under maintenance.

Guest

Each guest contains:

• ID
• First Name
• Last Name
• Email
• Phone
• Document Number
• Nationality

For example:

type Guest struct {
    ID             string
    FirstName      string
    LastName       string
    Email          string
    Phone          string
    DocumentNumber string
    Nationality    string
}

Reservation

A reservation belongs to:

• one hotel
• one primary guest

and may contain one or more rooms. A possible model is:

type Reservation struct {
    ID             string
    HotelID        string
    PrimaryGuestID string
    CheckInDate    time.Time
    CheckOutDate   time.Time
    Status         ReservationStatus
    CreatedAt      time.Time
}

Possible states:

pending
confirmed
checked_in
checked_out
cancelled
no_show

Reservation Rooms

A reservation may contain multiple rooms.

Do not duplicate the entire reservation for every room. A possible relationship model is:

type ReservationRoom struct {
    ReservationID string
    RoomID        string
    Adults        int
    Children      int
    NightlyRates  []NightlyRate
}

Date Interval Semantics

Reservation intervals use:

[check-in, check-out)

semantics. For example:

        Reservation A: June 10 -> June 12
        Reservation B: June 12 -> June 15

do not overlap.

Reservation A occupies nights:

June 10
June 11

and releases the room for another guest on June 12.

Overlapping Reservation Detection

Two active reservations for the same room conflict when:

A.CheckIn < B.CheckOut
AND
B.CheckIn < A.CheckOut

Cancelled reservations do not block availability.

The system must prevent double booking.

Availability Search

The system must support searches using:

• Hotel
• Check-In Date
• Check-Out Date
• Adults
• Children
• Required Room Count
• Optional Room Type
• Maximum Price

The result should contain only rooms that:

• have no conflicting reservation
• are not under maintenance
• are not out of service
• satisfy guest capacity

Multi-Room Search

A request may require several rooms. Example:

• 4 adults
• 2 children
• 3 rooms

The system should find a valid room combination.

The implementation must not independently return three rooms that cannot jointly satisfy the request.

Pricing

Room price may depend on:

• hotel
• room type
• date
• season
• promotion

The final reservation price must be calculated per night.

Nightly Rate

A useful model is:

type NightlyRate struct {
    Date      time.Time
    BasePrice float64
    Adjustment float64
    FinalPrice float64
}

The complete reservation price is:

• sum of all nightly rates
• for all reserved rooms

Seasonal Pricing

Create seasonal pricing rules. For example:

type SeasonalRate struct {
    HotelID      string
    RoomTypeID   string
    StartDate    time.Time
    EndDate      time.Time
    Multiplier   float64
}

Example:

        Base Price = 150
        Summer Multiplier = 1.20
        Night Price = 180

Promotions

A promotion may provide:

• percentage discount
• fixed discount
• minimum stay requirement
• date restriction
• room-type restriction

A possible model is:

type Promotion struct {
    ID             string
    HotelID        string
    PercentageOff  float64
    MinimumNights  int
    StartDate      time.Time
    EndDate        time.Time
}

The implementation must define deterministic behavior when several promotions match. For the base task:

select the single promotion producing the lowest valid final price

Promotions are not combined unless explicitly configured.

Reservation Quote

Before creating a reservation, the system should be able to generate a quote. For example:

type ReservationQuote struct {
    HotelID       string
    RoomIDs       []string
    CheckInDate   time.Time
    CheckOutDate  time.Time
    NightCount    int
    Subtotal      float64
    Discount      float64
    Total         float64
}

Generating a quote must not create a reservation.

Reservation Creation

When a reservation is created:

• validate guest
• validate hotel
• validate dates
• validate room capacity
• validate availability
• calculate price
• create reservation

For the base task, reservation creation across several rooms is atomic. Either:

all requested rooms are reserved

or:

no reservation is created

Reservation State Machine

Normal lifecycle:

        pending
           |
           v
        confirmed
           |
           v
        checked_in
           |
           v
        checked_out

Alternative states:

        pending -> cancelled
        confirmed -> cancelled
        confirmed -> no_show

Invalid transitions must be rejected. Examples:

        cancelled -> checked_in
        checked_out -> checked_in
        pending -> checked_out
        no_show -> checked_in

Payment

A reservation may contain several payments. For example:

type Payment struct {
    ID            string
    ReservationID string
    Amount        float64
    Method        PaymentMethod
    Status        PaymentStatus
    Timestamp     time.Time
}

Possible methods:

• card
• cash
• bank_transfer

Possible states:

• pending
• completed
• failed
• refunded

Deposit

A hotel may require a reservation deposit. For example:

20% of reservation total

The reservation may remain:

pending

until the required deposit is successfully processed.

Cancellation Policy

Different hotels may have different cancellation policies. A possible model:

type CancellationPolicy struct {
    ID                  string
    FreeCancellationHours int
    LateCancellationPercent float64
}

Example:

free cancellation until 48 hours before check-in
after that point, charge 50%

The cancellation operation must calculate any applicable charge.

No-Show

If a confirmed guest does not check in before the hotel’s configured no-show deadline:

Reservation.Status = no_show

The applicable policy determines the final charge.

Check-In

Check-in requires:

• confirmed reservation
• valid guest
• arrival date
• room ready
• room not under maintenance

The assigned room must be available before check-in. After successful check-in:

        Reservation.Status = checked_in
        Room.Status = occupied

Room Reassignment

A reserved room may become unavailable before guest arrival. For example:

• water leak
• maintenance failure
• electrical problem

The system should search for a replacement room. The replacement must:

• belong to the same hotel
• support required guest capacity
• be available for the complete reservation interval
• not reduce the booked room category unless explicitly allowed

Upgrade

If the originally reserved room cannot be used, the hotel may upgrade the guest. For the base task:

a free operational upgrade is allowed

when no equivalent room is available. The system must record the reassignment.

Stay

A stay represents the actual guest occupancy after check-in. A possible model is:

type Stay struct {
    ID            string
    ReservationID string
    ActualCheckIn time.Time
    ActualCheckOut *time.Time
}

Reservation and Stay should not be treated as identical concepts.

A reservation represents the commercial booking. A stay represents actual occupancy.

Hotel Services

Hotels may provide services such as:

• breakfast
• room_service
• parking
• spa
• laundry
• airport_transfer
• minibar

A possible model is:

type HotelService struct {
    ID      string
    HotelID string
    Name    string
    Price   float64
}

Service Usage

Guest service usage must be recorded. For example:

type ServiceCharge struct {
    ID        string
    StayID    string
    ServiceID string
    Quantity  int
    UnitPrice float64
    Timestamp time.Time
}

These charges become part of the final invoice.

Minibar

Minibar consumption may also be modeled as service charges. Example:

        Water     x2
        Juice     x1
        Snack     x3

Each item contributes to the guest invoice.

Housekeeping

After check-out:

Room.Status = dirty

The room cannot immediately become available for another check-in.

A housekeeping task must be completed first.

Housekeeping Task

A possible model is:

type HousekeepingTask struct {
    ID         string
    RoomID     string
    EmployeeID string
    Status     HousekeepingStatus
    CreatedAt  time.Time
    CompletedAt *time.Time
}

Possible states:

• created
• assigned
• in_progress
• completed
• cancelled

After successful cleaning:

Room.Status = available

provided no maintenance restriction exists.

Employee

Hotel employees may have roles such as:

• reception
• housekeeping
• maintenance
• manager

A possible model:

type Employee struct {
    ID      string
    HotelID string
    Name    string
    Role    EmployeeRole
    Status  EmployeeStatus
}

Tasks must only be assigned to employees with an appropriate role.

Maintenance

A room may become unavailable because of maintenance. A possible model is:

type RoomMaintenance struct {
    ID        string
    RoomID    string
    StartTime time.Time
    EndTime   time.Time
    Reason    string
    Status    MaintenanceStatus
}

During active maintenance:

• room cannot be assigned
• room cannot accept check-in

Maintenance Conflict

If maintenance is scheduled for a room that already has a future reservation, the system must report the conflict.

It must not silently invalidate the reservation. The hotel may then:

• move maintenance
• reassign guest
• cancel maintenance

according to the chosen operation.

Check-Out

At check-out:

• calculate room charges
• calculate service charges
• apply valid discounts
• calculate previous payments
• calculate remaining balance
• create final invoice
• complete payment
• close stay
• mark room dirty
• create housekeeping task

Invoice

A possible model is:

type Invoice struct {
    ID            string
    ReservationID string
    StayID        string
    Items         []InvoiceItem
    Subtotal      float64
    Discount      float64
    Total         float64
    Paid          float64
    Balance       float64
}

with:

type InvoiceItem struct {
    Description string
    Quantity    int
    UnitPrice   float64
    Total       float64
}

Invoice Consistency

The invoice must preserve the actual prices used.

Changing a room’s current base price after check-out must not change an already issued invoice.

Historical financial records must remain stable.

Occupancy

The system should calculate hotel occupancy for a date or date range. For example:

        Total Operational Rooms = 100
        Occupied Rooms = 82
        Occupancy = 82%

Rooms marked:

• maintenance
• out_of_service

should be distinguishable from normal unoccupied rooms.

Network Search

The system should support searching across all hotels. Example:

        City = any
        Check-In = July 10
        Check-Out = July 15
        Guests = 2
        Maximum Total Price = 1200

Results may be sorted by:

• lowest total price
• hotel name
• room category

The selected ordering must be deterministic.

Overbooking Scenario

Create a scenario where two reservation requests attempt to reserve the same last available room for overlapping dates.

Only one reservation may succeed. The final state must contain exactly one valid reservation for that room and interval.

The implementation does not require actual parallel execution.

It must model the operation so that availability validation and reservation creation behave as one consistent state change.

Multi-Hotel Scenario

Create a guest journey containing:

        HT01 — 3 nights
        HT02 — 2 nights
        HT04 — 4 nights

These are separate hotel reservations but may belong to one travel plan. An optional model is:

type TravelPlan struct {
    ID             string
    GuestID        string
    ReservationIDs []string
}

Failure or cancellation of one reservation must not automatically modify the others.

Audit History

State-changing operations should generate audit events. Examples:

• reservation created
• deposit received
• reservation confirmed
• room reassigned
• guest checked in
• service added
• guest checked out
• invoice created
• room marked dirty
• housekeeping completed
• reservation cancelled
• maintenance scheduled

A possible model is:

type AuditEvent struct {
    ID         string
    Timestamp  time.Time
    EntityType string
    EntityID   string
    Action     string
    Details    string
}

Idempotency

Important commands should contain unique request IDs. Examples:

• reservation creation
• payment processing
• check-in
• check-out
• service charge creation

Processing the same request twice must not:

• create duplicate reservations
• charge a guest twice
• check in twice
• create duplicate service charges
• create duplicate invoices

Query Operations

The system should support:

• search available rooms
• get reservation
• get guest reservations
• get hotel occupancy
• get current guests
• get room status
• get room maintenance
• get housekeeping queue
• get reservation payments
• get stay service charges
• get final invoice

Queries must not modify state.

Command Operations

State-changing operations include:

• create reservation
• confirm reservation
• process payment
• cancel reservation
• mark no-show
• reassign room
• check in guest
• add service charge
• check out guest
• schedule maintenance
• create housekeeping task
• complete housekeeping

Validation

The implementation should validate:

• duplicate IDs
• unknown hotel
• unknown room
• unknown room type
• unknown guest
• unknown employee
• unknown reservation
• invalid date interval
• check-out <= check-in
• room capacity exceeded
• reservation overlap
• room unavailable
• maintenance conflict
• invalid reservation transition
• invalid room transition
• negative price
• invalid payment amount
• duplicate request ID
• invalid promotion
• invalid cancellation policy

Required Test Scenarios

Create tests for at least:

• successful availability search
• no available room
• successful single-room reservation
• successful multi-room reservation
• overlapping reservation rejection
• back-to-back reservations
• room-capacity validation
• seasonal price calculation
• promotion selection
• reservation quote
• deposit processing
• reservation confirmation
• free cancellation
• late cancellation
• no-show
• successful check-in
• check-in rejected for unavailable room
• room reassignment
• free upgrade
• service charge
• successful check-out
• invoice generation
• room becomes dirty
• housekeeping completion
• maintenance conflict
• occupancy calculation
• network-wide hotel search
• duplicate reservation request
• duplicate payment request
• duplicate check-out request

Modeling Goal

The purpose of this task is to model a reservation system where commercial and operational state must remain consistent.

A useful conceptual architecture is:

        Hotel Registry
              |
              +-- Hotels
              +-- Rooms
              +-- Room Types
              |
              v
        Availability Service
              |
              +-- Date Intervals
              +-- Capacity
              +-- Maintenance
              |
              v
        Pricing Service
              |
              +-- Base Rates
              +-- Seasonal Rates
              +-- Promotions
              |
              v
        Reservation Service
              |
              +-- Booking
              +-- Cancellation
              +-- Reassignment
              |
              v
        Stay Service
              |
              +-- Check-In
              +-- Services
              +-- Check-Out
              |
              v
        Hotel Operations
              |
              +-- Housekeeping
              +-- Maintenance
              |
              v
        Billing Service
              |
              +-- Payments
              +-- Charges
              +-- Invoice
              |
              v
        Audit History

The main challenge is keeping reservations, room availability, actual occupancy, pricing, payments, housekeeping, maintenance, and billing consistent across the complete guest lifecycle.