UC: Booking Details — Personalised Recommendations

uc-booking-recommendations.md

UC: Booking Details — Personalised Recommendations

Domain: Smart Features Status: Draft

Description: When the guest opens a booking details screen, the frontend triggers a recommendation request to the AI service. The AI fetches guest data and booking history from MyMate API, enriches it with external data sources (weather, local events, etc.), and streams back personalised recommendations for the remaining stay.

Conversation Example:

Guest opens booking details for their Grand Plaza stay (3 nights left).

AI: "Here are some suggestions for your stay:
     🌧 Rain forecast tomorrow — perfect for the Spa Basic Package
       (09:00, 150 MAD)
     🍽 You enjoyed seafood at Beach Grill — Le Plaza has a similar
       tasting menu tonight at 19:30
     🏄 You went snorkeling at Seaside — try the City Tour here
       (half-day, tomorrow 08:00, 50 MAD)"

Performance Strategy:

• Screen renders immediately with booking details (already fetched)
• Recommendations section shows a skeleton/shimmer placeholder
• AI request fires in background, results streamed via SSE
• Cards animate in one by one — first card appears in ~1-2s
• Total completion ~3-5s, but perceived wait is minimal

Full Flow:

sequenceDiagram
    participant FE as Front End
    participant AI as AI Service
    participant EXT as External APIs
    participant API as MyMate API

    Note over FE: Screen loads instantly.<br/>Skeleton in recommendations section.

    FE->>AI: POST /recommend (SSE)<br/>{ booking: "/bookings/bkg_xxx" }

    par MyMate API calls
        AI->>API: GET /guests/{id}
        AI->>API: GET /bookings/{id}
        AI->>API: GET /restaurant_bookings<br/>?order[startTime]=desc&itemsPerPage=10
        AI->>API: GET /activity_bookings<br/>?order[startTime]=desc&itemsPerPage=10
        AI->>API: GET /restaurants?iri[hotel]=...
        AI->>API: GET /activities?iri[hotel]=...
        AI->>API: GET /services?iri[hotel]=...
    and External API calls
        AI->>EXT: GET weather forecast
        AI->>EXT: GET local events
    end
    API-->>AI: guest, booking, history, available options
    EXT-->>AI: weather, events

    Note over AI: LLM reasoning:<br/>- Guest profile & preferences<br/>- Recent dining history (last 10)<br/>- Recent activity history (last 10)<br/>- Available hotel options<br/>- Weather forecast<br/>- Local events<br/>- Remaining stay duration

    AI-->>FE: SSE: recommendation 1
    Note over FE: Card animates in
    AI-->>FE: SSE: recommendation 2
    AI-->>FE: SSE: recommendation 3
    AI-->>FE: SSE: done

Loading

Front End Requirements:

• Render booking details screen immediately (no blocking on recommendations)
• Show skeleton placeholder in recommendations section
• Connect to SSE endpoint for streamed recommendations
• Render each recommendation card as it arrives (animate in)
• Each card shows: type icon, title, reason, price, time/availability
• Each card links to the relevant booking flow (restaurant, activity, service)
• Cache recommendations for the session to avoid repeated calls

AI Service Requirements:

• Fire all MyMate API calls in parallel (~100-150ms total, not sequential)
• Fire external API calls (weather, local events, etc.) in parallel with MyMate calls
• Limit history queries to last 10 items (order[startTime]=desc&itemsPerPage=10) — enough for pattern detection without fetching years of data
• Fetch activity variants for available activities (iri[activity]=...) for pricing and scheduling
• Stream recommendations via SSE as the LLM generates them
• Build 3-5 personalised recommendations considering:
  • Past dining patterns → similar cuisine at current hotel
  • Past activity history → suggest new experiences, avoid repeats
  • Untried services this stay → suggest them
  • Weather forecast → indoor activities on rainy days
  • Local events → time-sensitive opportunities
  • Guest preferences & profile → personalise tone and picks
  • Remaining nights → time-appropriate suggestions

What exists (MyMate API):

• Guest details via GET /guests/{id} — includes preferences, gender, birthdate ✓
• Booking details via GET /bookings/{id} — includes rooms, hotel, dates ✓
• Restaurant booking history — auto-filtered by guest JWT (GuestExtension) ✓
• Activity booking history — auto-filtered by guest JWT (GuestExtension) ✓
• Restaurant/activity/service browsing by hotel ✓
• Activity variants with pricing and schedules ✓
• Guest preferences entity ✓

External APIs (AI Service responsibility, not MyMate API):

• Weather forecast API — for weather-based suggestions
• Local events API — for time-sensitive recommendations
• Other enrichment sources as needed by the AI team

MyMate API Endpoints:

• GET /guests/{id} — guest profile, preferences, gender, birthdate
• GET /bookings/{id} — current booking details (hotel, dates, rooms)
• GET /restaurant_bookings?order[startTime]=desc&itemsPerPage=10 — recent dining history (auto-filtered by guest JWT)
• GET /activity_bookings?order[startTime]=desc&itemsPerPage=10 — recent activity history (auto-filtered by guest JWT)
• GET /restaurants?iri[hotel]=... — available restaurants at current hotel
• GET /activities?iri[hotel]=... — available activities at current hotel
• GET /activity_variants?iri[activity]=... — variant details (price, schedule, duration)
• GET /services?iri[hotel]=... — available services at current hotel