Skip to main content

01 — Frontend Product Overview

Scope: What the Ghasi Melmastoon frontend platform is, who it is for, what it must do, and the non-negotiable product constraints every screen and surface inherits. This is the entry doc for any FE contributor (engineer, designer, PM, QA).

Companions: 02-architecture-overview-frontend.md · 03-design-system.md · 04-frontend-design-guidelines.md · 06-theming-and-tenant-config.md · 09-non-functional-requirements.md

1. What we are building​

A multi-tenant hospitality operating system for hotels, guesthouses, and serviced-residence operators in Afghanistan, Pakistan, and the broader Central / South Asian region. The frontend layer is the surface area through which every persona — guest, hotel staff, owner, super-admin, OTA partner, kiosk user — accomplishes their work.

The platform spans eight surfaces delivered across four runtimes from one design system, one i18n bundle, and three BFFs.

#SurfaceRuntimeAudienceTenant contextPrimary BFF
1Consumer Meta WebBrowser (PWA)Guests browsing across tenantsPre-tenantbff-consumer-service
2Tenant Booking WebBrowser (PWA)Guests committed to a tenantIn-tenantbff-tenant-booking-service
3Guest Portal WebBrowser (auth)Guests mid-stay / post-stayIn-tenantbff-tenant-booking-service
4Consumer MobileiOS + Android (RN)Guests on phonesBothboth consumer + tenant booking BFFs
5Staff Mobile CompanioniOS + Android (RN)Housekeeping / maintenance / F&BIn-tenantbff-backoffice-service
6Operator DesktopElectron (Win/Mac/Linux)Front desk / GM / financeIn-tenantbff-backoffice-service
7Kiosk familyElectron in kiosk modeLobby self-checkin / housekeeping board / arrivals TVIn-tenantbff-backoffice-service
8Control Plane WebBrowser (auth)Super-admin / chain operatorCross-tenantbff-backoffice-service (admin scope)

Plus two distribution surfaces (covered separately): Embeddable booking widget for tenant external sites, and OTA partner portal for B2B distribution.

2. Personas​

PersonaPrimary surface(s)Secondary surface(s)FrequencyCritical KPI
Guest (browser)Consumer Meta WebTenant Booking WebOne-time / occasionalTime-to-confirm; payment success
Guest (mobile)Consumer MobileGuest Portal WebOne-time / occasional + post-stayCold-start; biometric login adoption
Walk-in / kiosk guestSelf-checkin Kiosk—Single-sessionTime-to-key; abandonment-step
Front desk / receptionistOperator DesktopTablet front-desk; Self-checkin KioskAll shiftCheck-in seconds; no-bookings-lost
Housekeeping leadOperator Desktop (HK board)Housekeeping KioskAll shiftRooms-cleaned-per-hour
Housekeeper (line)Staff Mobile CompanionHousekeeping KioskAll shiftStatus-update latency; offline tolerance
MaintenanceStaff Mobile CompanionOperator DesktopAll shiftTime-to-resolve
F&B runnerTablet POSStaff Mobile CompanionAll shiftOrder-to-table seconds
FinanceOperator DesktopControl Plane WebDaily / monthlyReconciliation-error rate
GM / OwnerOperator DesktopControl Plane Web; mobile read-only viewsDailyRevPAR; AI-insight adoption
Chain OperatorControl Plane WebOperator Desktop (impersonation)DailyCross-tenant comparability
Super-adminControl Plane Web—DailyTenant-onboarding time; outage MTTR
OTA PartnerOTA Partner Portal—Daily / hourlyAllotment freshness
Compliance OfficerControl Plane WebOperator Desktop (audit log viewer)EpisodicAudit-trail completeness

Each persona's full journey set lives in ../journeys/.

3. Non-negotiables (frontend slice)​

These six constraints govern every FE choice. None are negotiable without an ADR.

  1. Three apps, one design system. All client surfaces consume @ghasi/ui-melmastoon. Raw hex / arbitrary fonts / bespoke spacing in app code are linted out.
  2. All tenant variation is data, not code. No if (tenantId === ...) branches in shared apps; theming and config flow through theme-config-service only.
  3. All API access goes through a BFF. Direct domain-service calls from web/mobile/desktop are forbidden.
  4. RTL + LTR are first-class. Pashto, Dari, Persian, Arabic, English (Urdu Phase 1, French Phase 2). Logical CSS properties everywhere; mirrored iconography is explicit per @ghasi/icons/manifest.json.
  5. Offline behaviour is opinionated and tiered. Web has a PWA browse cache; mobile caches recent results in MMKV; desktop is genuinely offline-first with a real local DB and a real sync engine (see ../desktop/21-desktop-app-specification.md).
  6. AI is HITL by default. No frontend ever auto-applies an AI suggestion that mutates guest-facing state (rate, refund, message send, key issuance) without an explicit human accept; provenance is rendered, not hidden.

Performance budgets, accessibility targets, and security posture follow from these and are enforced in CI — see 09-non-functional-requirements.md.

4. Product pillars​

Each pillar is the through-line for several journeys and several KPIs.

4.1 Guest experience that beats global OTAs in the region​

  • Sub-2.5s LCP on Moto G4 / Slow 4G for the Consumer Meta Web home and detail screens
  • First-class Pashto / Dari / Urdu RTL — no other regional booking engine ships this fidelity
  • Cash-on-arrival as a first-class payment radio, not a footnote
  • Trust-by-default UX (no dark patterns; ethical urgency; honest social proof)

4.2 Operator experience that beats Mews / Cloudbeds for small/mid hotels​

  • Genuinely offline-first desktop — front desk does not lose a booking when the ISP fails
  • One-click sub-second navigation between front-desk, housekeeping, finance views
  • Operator copilot (HITL): "draft a reply", "summarize stay", "explain anomaly", "suggest upsell"
  • Tenant-customizable booking sites without code (block & page builder)

4.3 Multi-channel that respects regional realities​

  • SMS-first fallback in regions where push notifications are unreliable
  • WhatsApp Business as a transactional channel
  • Voice / IVR integration for guest concierge in Phase 2
  • Embeddable booking widget for tenant external sites (WordPress / Wix)

4.4 Operational realism​

  • Low-bandwidth / data-saver mode across all consumer surfaces
  • Local-AI on desktop (ONNX Runtime Node) when GPU available; cloud fallback otherwise
  • Lock vendor independence: encoder USB/serial Phase 1; BLE / NFC Phase 2; mobile key with Apple/Google Wallet Phase 2

4.5 Trust, safety, compliance​

  • WCAG 2.2 AA across every surface, audited per release
  • GDPR data-subject self-service from the Guest Portal
  • Tenant data isolation visible in the UI (no cross-tenant leak in admin search results, no cross-tenant theme bleed)
  • AI provenance rendered in every AI-generated artifact

5. Surface release sequencing (high-level)​

ReleaseSurfaces in scopeOut of scope
R1Consumer Meta Web (search/detail/handoff), Tenant Booking Web (booking funnel + cash-on-arrival + card via Adyen), Consumer Mobile (browse + book), Operator Desktop (front desk + housekeeping board + finance basics)Guest Portal (/manage); Control Plane (super-admin); Kiosk family; Tablet POS; Embed widget; OTA portal; Staff Mobile Companion; mobile-key BLE/Wallet; in-product AI surfaces
R2Guest Portal Web; Self-checkin Kiosk; Staff Mobile Companion; Embed widget; Operator copilot HITL surface; OpenSearch 2.x migration for meta search (R1 runs Postgres FTS)AR room preview; voice/IVR; chain switcher
R3+Tablet front-desk + POS; Arrivals-board kiosk; OTA partner portal; Owner Insight assistant; Mobile-key BLE/Wallet; AR/wayfinding—

Detailed sequencing per epic is in ../../roadmap/01-release-1-foundations.md.

6. What "rich, state-of-the-art UI" means here​

Not "Bootstrap clone with our colors". Concretely:

  • Motion is choreographed, not decorative — drag-drop on the housekeeping board uses spring physics; success states use a 320 ms confetti micro-animation; error states shake then settle in 240 ms; reduced-motion users see a 100 ms opacity transition instead.
  • Loading states are named patterns, not generic spinners — skeleton screens that match final layout; data-shape-aware empty states with an action; progressive disclosure for long lists.
  • Iconography is curated — Phosphor base set + ~20 custom hospitality glyphs (bed, breakfast, prayer-room, halal-kitchen, women-only-floor) + RTL mirror flags.
  • Photography is art-directed — every property has a hero, gallery, and at least one 360° tour by R3.
  • Microcopy is reviewed — voice-and-tone is documented per locale; no auto-translated strings ship without human review.
  • Density modes are real — cozy for guest surfaces, comfortable for operator desktop default, compact for power-user dashboards.

The full design system inventory is in 03-design-system.md; the choreography library is in ../catalogs/C10-motion-and-microinteractions.md; the voice & tone guide is in ../catalogs/C12-content-voice-and-tone.md.

7. Out of scope for any FE doc in this set​

  • Backend service implementation details — see ../../03-microservices/ and ../../services/<svc>/
  • Domain event topic semantics — see ../../04-event-driven-architecture.md
  • Lock vendor protocol / firmware specifics — see ../../09-lock-and-key-integration.md
  • Payment provider gateway internals — see ../../10-payments-architecture.md
  • AI model training / RAG corpus building — see ../../08-ai-architecture.md
  • Infrastructure provisioning — owned by platform repos, not docs

8. Open questions​

  • Will the Consumer Mobile app ship a "guest concierge chat" surface in R2, or is that R3? Current AI architecture doc puts it as Phase 2; product PM hasn't confirmed.
  • Does the OTA Partner Portal ship as a separate Next.js app or a route group inside the Control Plane? Affects auth model.
  • For mobile-key, do we ship the Apple/Google Wallet pass first (lower vendor coupling) or the in-app BLE unlock first (better UX)? Depends on first lock-vendor-with-BLE go-live.

References​