Skip to main content

15 — Guest Portal Web Specification

Surface: Guest Portal Web (/manage — auth-gated, in-tenant context) BFF: bff-tenant-booking-service (guest-authed scope) Audience: Guests mid-stay or post-stay who want to manage their booking, request services, or review their folio Feature flag: guest-portal (default: false; enabled per tenant in R2) Competitive reference: Marriott Bonvoy app, Hilton Digital Key, Duve guest portal

1. Overview​

The Guest Portal is the in-stay and post-stay self-service interface for guests. It is accessible at:

  • https://<tenantSlug>.melmastoon.app/manage (tenant-branded)
  • Or https://melmastoon.app/<tenantSlug>/manage (platform-hosted)

Guests log in with the email + reservation reference they used at booking. No new account creation is required.

Capabilities (R2):

  • View booking details and folio.
  • Submit mid-stay service requests (cleaning, amenities, maintenance).
  • View pre-arrival information (directions, check-in instructions, local recommendations).
  • Download receipt / invoice.
  • Request late checkout.
  • Submit post-stay review (if review service is active).

Capabilities (R3+):

  • BLE / digital key management.
  • F&B ordering (if POS is configured).
  • Chat with property staff.

2. Auth model​

Guests authenticate using a magic link sent to their booking email:

  1. Guest enters email + reservation reference.
  2. BFF (bff-tenant-booking-service) sends a short-lived OTP link via notification-service.
  3. Guest taps link → authenticated session (guest_token) stored as SameSite=Lax; HttpOnly cookie.
  4. Session scoped to the single reservation; expires at checkout + 7 days.

No password required. No Ghasi platform account required (though guests may optionally create one for cross-stay history).

3. Route tree​

/<locale>/<tenantSlug>/manage/
├── /login                    ← Email + reservation ref form; OTP request
├── /                         ← Home (booking summary + quick actions)
├── /booking                  ← Full booking detail + folio
├── /services                 ← Request housekeeping, amenities, maintenance
├── /requests                 ← My submitted requests + status
├── /directions               ← Map + transport options + check-in instructions
├── /receipt                  ← Download PDF receipt (PD-01)
├── /checkout                 ← Late checkout request (if tenant enables)
└── /review                   ← Post-stay review form (R2+)

4. Key screens​

4.1 Home​

Sections:

  1. Booking header: property name + logo, room number, check-in / check-out dates, countdown ("2 nights remaining").
  2. Quick action grid: "Request cleaning", "Need something?", "Directions", "My folio", "Download receipt".
  3. Property announcements (tenant-authored messages, optional).
  4. Property info strip: check-out time, Wi-Fi password (encrypted at rest, decrypted on display), emergency contacts.

4.2 Booking detail + folio​

Sections:

  1. Reservation details (ref, dates, room, rate plan, guests).
  2. Folio: itemized charges posted so far. Refreshed every 60 s.
  3. Balance due at checkout (estimated).
  4. Cancellation / modification CTA (if policy allows — links back to booking funnel modification flow).

Offline: Folio cached at last fetch; "Showing data as of <time>" label.

4.3 Service requests​

Request types (per tenant.serviceRequests config):

RequestIconFields
Cleaning requestBroomPreferred time (time picker), special instructions
Extra towels/linensTowelQuantity (stepper)
Amenity requestSparklesSelect from approved list (pillows, toiletries, etc.)
Maintenance reportWrenchDescription (textarea), photo (optional)
Do not disturbSignToggle (DND active / inactive)

Submit: POST /tenant-booking/v1/service-requests. Creates a housekeeping or maintenance ticket in the backoffice.

Status tracking: After submission, the request shows "Received → In progress → Completed" status (polled every 30 s).

4.4 Directions & check-in info​

  • Leaflet mini-map with property pin.
  • Address + "Open in Google Maps / Apple Maps / Waze" links.
  • Transport options (taxi, bus, car): tenant-authored text.
  • Check-in time, early check-in policy.
  • Key issuance instructions (for self-checkin kiosk if available).

5. Theming​

Same tenant theme as the booking funnel (C7 — same ThemeVersion from theme-config-service). Guest portal is visually consistent with the tenant's booking experience.

6. Offline behavior​

The guest portal is not offline-first — it requires a connection for real-time folio updates and service requests. However:

  • Booking summary and directions are cached on first load (Service Worker, CacheFirst 1 h).
  • If offline: show C3 ER-07 offline banner; disable service request form; show cached folio with timestamp.

7. Accessibility​

  • WCAG 2.2 AA.
  • Large tap targets (48 × 48 px minimum on touch) — guests are often using their phone with one hand.
  • High-contrast mode: detect prefers-contrast: more and increase text contrast to AAA.
  • All icons have visible text labels (not icon-only buttons).

8. Open Questions​

  • Should late checkout requests be auto-approved if a rule allows it (e.g., room is not reserved for the next night), or always require front-desk approval?
  • Should the guest portal support multiple reservations under the same email in a single session, or one reservation per session?
  • Photo for maintenance reports: should it go through file-storage-service directly (large upload) or be compressed client-side to < 500 KB first?
  • Post-stay review: what's the moderation flow? Tenants can flag reviews; platform moderates disputes?

References​