BUSINESS.md: Hotel8:eGuest — Business Requirements & Functionality
Audience: product owners, business analysts, and anyone evaluating what Hotel8:eGuest does for the business. For architecture read
README.md; for wire-level detail readDESIGN.md.
1. Business Purpose
- Move the stay journey into the guest's hand: pre-arrival registration, mobile check-in, in-stay requests and messaging, and express check-out — reducing front-desk workload and queueing.
- Grow ancillary revenue by surfacing upsell offers (upgrades, early check-in, amenities) at the right journey moments with one-tap acceptance.
- Deepen loyalty engagement with points visibility and stay feedback, and feed property managers structured satisfaction data.
- Reduce payment friction: guests review their folio and settle outstanding balances before departure.
2. Business Scope (What the Service Provides)
| Capability | Provided by eGuest |
|---|---|
| My Stays (reservation list) | ✅ |
| Pre-check-in (registration card, arrival time) | ✅ |
| Mobile check-in with room assignment view | ✅ |
| Digital key: view, activate, deactivate | ✅ |
| Upsell offers: view/accept/decline | ✅ |
| Service requests: submit + track | ✅ |
| Guest messaging with front desk | ✅ |
| Folio review + quick pay (express check-out) | ✅ |
| Mobile check-out with settled folio | ✅ |
| Stay feedback rating | ✅ |
| Guest profile + preferences update | ✅ |
| Loyalty member summary + transaction list | ✅ |
| Room service / F&B ordering | ✅ dine tab — orders from the room-service menu, bound to the in-house stay (POS guest surface) |
| Rewards catalog + redemption + tier progress | ✅ offers tab — catalog with redeemable flags; redemption returns a voucher code |
| Payment-method management | ✅ profile tab — saved bill8 token references (add/remove) |
| New bookings | ❌ delegated — Hotel8:eBooking |
| Lobby kiosk key dispensing | ❌ delegated — Hotel8:eKiosk |
| Staff responses to requests/requests | ❌ delegated — Hotel8:ePMS |
| Push deep-link landing (room-ready / request updates) | ✅ URL contract (?tab=/path routes land on the target tab); mobile push credentials pending the Post integration |
3. Business Capabilities
Pre-arrival & check-in
| Capability | Business rule |
|---|---|
| Pre-check-in | The guest completes the registration card (identifiers, arrival time, special requests) before arrival; PMS retains it so front-desk interaction shrinks to key issuance. |
| Mobile check-in | Check-in executes against the PMS front office with the room assigned server-side; the guest sees the room only when the property releases it. |
| Digital key | Keys follow the property's policy: guest can activate/deactivate keys the PMS has issued — never fabricate a key. |
In-stay
| Capability | Business rule |
|---|---|
| Service requests | Requests are typed (housekeeping, maintenance, amenities, wake-up) and tracked through their PMS lifecycle; the guest sees status, not staff internals. |
| Messaging | Threads are stay-scoped; front-desk replies appear in the same thread. |
| Upsell offers | Offers are generated by Hotel8:Upsell; accepting charges the guest via Payments and applies the upgrade in PMS; a declined offer is never re-presented by the client. |
| Room-service ordering | Orders come from the property's room-service menu and bind to the in-house stay (room + reservation resolve server-side — the guest never types a room number); prep states (sent/preparing/ready/served) drive the status stepper; the charge posts to the stay's folio via the POS check. |
| Rewards redemption | The catalog shows each reward's points cost and whether the member's balance covers it; redeeming exchanges points for a voucher code the guest presents at the desk — points never go negative. |
| Saved payment methods | Methods are token references (Payments tokenizes the instrument; the app stores the reference only — the guest never re-enters card numbers); a saved default covers folio quick-pay. |
| Folio review | The guest sees the authoritative folio (charges, payments, balance) — no local estimate. |
| Quick pay / express check-out | Payment covers the outstanding balance; check-out only completes when the folio is fully settled server-side. |
Post-stay & profile
| Capability | Business rule |
|---|---|
| Feedback | A rating submits into the PMS feedback store; one rating per stay journey step. |
| Profile & preferences | The guest updates their own profile fields only; identity data is customer-env scoped. |
| Loyalty visibility | Members see balance and their transaction list; enrollment/earning rules live in Loyalty. |
4. Business Events (Outbound)
eGuest is a client; it emits no events. Guest actions trigger events in the owning services (see their DESIGN docs):
| Business moment | Event family (owner) |
|---|---|
| Registration card stored / check-in executed | PMS front-office events |
| Service request created | PMS request events |
| Message exchanged | PMS messaging events |
| Digital key activated/revoked | PMS key events |
| Offer accepted/declined | Upsell offer events |
| Check-out posted / folio settled | PMS cashiering events |
| Feedback submitted | PMS feedback events |
Inbound (notification-side): the guest receives push/email notifications produced by Sentin8:Post from those domain events (room ready, order/request status).
5. Business Rules & Invariants
- All guest traffic is BFF-proxied; the app cannot reach PMS, Upsell, Payments, or Loyalty directly.
- A stay's data is visible only to its guest — server-side holder-scoping owns enforcement.
- Keys are created/issued by the property; guests can only activate/stop issued keys.
- An upsell acceptance routes through Payments; a decline is final until the service generates a new offer.
- Check-out requires a fully settled folio; partial payment leaves the stay in-house.
- Folio figures shown are the PMS folio, never a client-total.
- Requests and messages are stay-scoped; a guest cannot read another stay's threads.
6. Target-User Roles & Use Cases
| Persona | What they do with eGuest |
|---|---|
| Hotel guest (pre-arrival) | Reviews stay, completes registration, accepts an upgrade. |
| Hotel guest (in-house) | Uses digital key, requests services, chats with front desk, reviews folio. |
| Hotel guest (departing) | Settles folio and checks out from the room, gets a receipt. |
| Loyalty member | Follows points earned from the stay and keeps profile preferences current. |
| Property manager | Benefits from reduced front-desk load and structured feedback data. |
7. KPIs / Success Criteria
- Share of check-ins via mobile/kiosk vs front desk.
- Upsell acceptance rate and ancillary revenue per stay.
- Request resolution visibility — guests see status without calling the desk (reduce inbound calls).
- Express check-out share and folio settlement timing (fewer depart-day queues).
- Feedback coverage (rating submission share) and satisfaction trend.
- Security: zero key activations outside PMS-issued keys; zero cross-stay data exposures.
8. Dependencies & Reliance on Other Services
| Reliance | For |
|---|---|
| Hotel8:PMS | Stays, registration, check-in/out, folio, keys, requests, messages, feedback |
| Hotel8:Upsell | Offers and their lifecycle |
| Bill8:Payments | Folio payments (via BFF) |
| Hotel8:Loyalty | Member summary + transactions |
| Sentin8:BFF | Transport, guest session, tenant resolution |
| Sentin8:Auth (customer env) | Guest identity (via BFF) |
| Sentin8:Post | Guest notifications |
| Hotel8:eBooking | The booking that creates the stay |
| Hotel8:eKiosk | Key dispensing alternative (QR round-trip) |
9. Acceptance Criteria
- A guest completes pre-check-in and then checks in on the phone, seeing the assigned room and (if enabled) an active digital key.
- A request submitted in-stay appears in the PMS staff queue and its status is visible in the app.
- A message thread shows guest and front-desk messages in order for the current stay.
- An accepted upsell charges the guest and reflects in the folio.
- A guest checks out only after their folio balance reaches zero, and the stay moves to departed in PMS.
- Feedback submitted for a stay is recorded with the guest's identity and the stay reference.
- All guest calls are
/proxy/*; no backend endpoint appears in traces.
10. Open Business Questions
- Does room-service ordering ride the POS proxy menu contract, and which revenue center owns delivery?
- Rewards catalog + redemption screens: Loyalty API surface timing.
- Mobile-key handoff per lock vendor: BLE and NFC both, or property choice?
- Push notification depth: which journey events notify, and when is email preferred?
Design attribution: hotel8:eguest and its underlying concepts were designed by Hamid Jahanzad Hamid@Jahanzad.com.