01 — Product Overview
Companion: README · Service Index · Enterprise Architecture
This document is the canonical product overview for Ghasi Melmastoon. It establishes identity, problem framing, surfaces, personas, value propositions, feature surface area, competitive positioning, geographic strategy, operating modes, success metrics, and explicit out-of-scope boundaries. All downstream specs (architecture, microservices, frontend, journeys, roadmap, ADRs) inherit definitions from this document.
1. Identity & Naming
1.1 Name
Ghasi Melmastoon (Pashto: د غاسي ملمستون).
1.2 Tagline
Hospitality, locally rooted, globally ready.
1.3 Etymology of "melmastoon"
Melmastoon (ملمستون) is the Pashto word for guesthouse and, by extension, for the institution of hospitality itself. It derives from melma (ملمه, "guest") + the suffix -stoon (ـستون, "place of"). It is the lexical and cultural cousin of melmastia (ملمستيا) — the Pashtunwali obligation of unconditional hospitality to a guest, regardless of cost, identity, or circumstance.
The brand choice is deliberate. Hospitality is not a feature of this product. It is the operating ethos and the design constraint:
- Defaults protect the guest experience. No automatic cancellation without operator confirmation; default grace periods on late checkout; AI suggestions are never auto-applied to guest-facing state.
- The product respects local context before global convention — Pashto / Dari / Persian first, Hijri and Solar Hijri calendars first-class, cash-on-arrival as a real payment method, not a workaround.
- The product respects the operator — touch-friendly affordances, undo-everywhere, voice-friendly labels, "Try this?" instead of "Apply this".
1.4 Elevator pitch
Ghasi Melmastoon is a multi-tenant hotel SaaS that fuses three things small/medium hoteliers in low-resource markets cannot otherwise get in one product: a consumer meta-search experience where travelers discover and book without leaving the platform, a tenant-branded booking experience generated from one shared codebase with per-tenant theming, and an AI-first, offline-first Electron desktop backoffice that runs the property's daily operations even when the internet does not.
2. Problem Statement
Small and medium hoteliers in Afghanistan, Tajikistan, and Iran — and in structurally similar markets across Central Asia, MENA tier-2, the Sahel, and South Asia — operate under conditions that mainstream hotel software does not solve for. The cumulative result is that the modal small/medium hotel in these markets uses WhatsApp, Excel, and a paper register as its operating system.
| Constraint | Field reality | Impact on existing software |
|---|---|---|
| Unreliable internet | Frequent outages, throttled bandwidth, expensive mobile data, hours-long blackouts in some districts | Cloud-only PMS becomes unusable; staff fall back to paper, then re-key data hours later, with errors |
| Intermittent power | Daily load-shedding, generator-only nights, voltage spikes that crash servers and POS terminals | Long-running cloud sessions die mid-flow; on-prem servers are unaffordable and fragile |
| Mixed tech literacy | One generalist IT person across multiple properties (or none); staff trained on the previous PMS by rote | Implementations stall; vendors require expensive consultants; new features go unused |
| Cash-heavy economy | Card penetration is low; trust gates payment to physical handover; agents move cash physically | Card-only payment systems exclude the majority of bookings; reconciliation is manual and lossy |
| RTL languages, mixed scripts | Pashto, Dari, Persian, Arabic; staff switch between Pashto and Dari mid-task; numerals vary (Arabic-Indic vs European) | English-only or partial Arabic UI; staff translate mentally on every screen; data-entry errors compound |
| Currency volatility | AFN, IRR, PKR move materially intra-day; guests pay in USD or EUR; OTAs settle in a third currency | Single-currency folios create reconciliation pain; reported revenue drifts from cash position |
| OTA fragmentation | Booking.com, Agoda, Expedia, regional OTAs, local agents, walk-ins, calls — each with its own inventory and price | Overbooking, price leakage, no single source of truth; OTAs take 15-25% commission |
| Fragmented lock hardware | Mix of mechanical keys, RFID cards, mobile credentials, and generic Wiegand controllers from cheap regional vendors | Vendor-locked PMS support 1-2 lock brands; the rest stays manual |
| Per-room USD pricing | Mainstream PMS charge per-room/month in USD, billed annually | Unaffordable for 8-50 room independents on thin local-currency margins |
| Disconnected meta-search | Trivago-style products list properties but hand the booking off to OTAs | Hoteliers cannot retain the guest relationship or the margin |
Ghasi Melmastoon replaces that stack with one platform that respects these constraints rather than ignoring them.
3. Platform Surfaces
Ghasi Melmastoon ships four user-facing surfaces plus a small platform-staff control plane. All four surfaces share the design tokens (@ghasi/ui-melmastoon), the i18n bundle, the API contracts in docs/05-api-design.md, and the AI provenance contract enforced by ai-orchestrator-service.
| # | Surface | Audience | Primary tech | Primary BFF | Online req. |
|---|---|---|---|---|---|
| 1 | Consumer Meta Web | Guests browsing across tenants | Next.js (App Router), TailwindCSS, Leaflet, React Query, PWA shell | bff-consumer-service | Online (PWA browse cache) |
| 2 | Consumer Mobile | Guests on phones | React Native (single multi-tenant app) | bff-consumer-service | Online (offline cache for last results) |
| 3 | Tenant Booking Web/Mobile | Guests inside a tenant context | Next.js (web) + the same React Native app rendering the tenant theme | bff-tenant-booking-service | Online (graceful degradation on payment) |
| 4 | Backoffice Desktop | Hotel staff and management | Electron (Node 20 main + Chromium renderer) + Vite + React + SQLite (better-sqlite3) + ONNX Runtime Node | bff-backoffice-service | Offline-first, sync when online |
3.1 Consumer Meta Layer (web + mobile)
A Trivago-style meta-search experience with one critical inversion: the booking does not leave the platform. Search inputs (location, check-in/out, guests, rooms, filter band) drive search-aggregation-service; results render in list view (provider, photo, min/max price, availability summary, rating) and map view (Leaflet pins with quick-info popovers). On selection, the user transitions into the tenant's themed booking flow inside the same app — same bundle, same session, swapped theme and policies. The URL changes to the tenant subdomain or path; the routing transition is mediated by bff-consumer-service and bff-tenant-booking-service.
What is unique: no OTA handoff, no commission, retained guest relationship for the hotelier, and a unified analytics surface across discovery and booking.
3.2 Tenant Booking Site (web)
A single shared Next.js codebase. Tenant theming is applied at runtime via theme-config-service — logo, color tokens, type ramp, layout preset, content blocks (about, policies, FAQs). Tenants pick presets, not arbitrary HTML. This protects accessibility, performance, and security; it also makes onboarding a configuration job, not an engineering job. Booking flow: room selection → rate selection → date / guest adjustments → special requests → payment method → confirmation → email / SMS / WhatsApp receipt + pre-arrival sequence. Full RTL/LTR. Locale-aware formatting for dates (Gregorian + Hijri + Solar Hijri presentational variants), currencies, and numerals.
What is unique: per-tenant brand experience without per-tenant forks, governed by a token + preset model.
3.3 Consumer Mobile App
A single React Native app, multi-tenant aware. Discovers across tenants, then renders the tenant booking flow under the tenant theme. Offline browse cache for the last set of results, but payment flows always require connectivity. Shares @ghasi/ui-melmastoon design tokens and the i18n bundle with the web surfaces — token changes propagate in one PR.
What is unique: one consumer app for the entire platform, not one per tenant.
3.4 Backoffice Desktop App (Electron, AI-first, offline-first)
The canonical operational surface for hotel staff and management. Built on Electron (Node 20 main process + Chromium renderer), Vite + React in the renderer, SQLite via better-sqlite3 as the local store, and ONNX Runtime Node for offline AI inference. Packaged with electron-builder, signed, and updated through electron-updater.
The desktop app mirrors the operational subset of platform state needed to run the property when the internet is off: reservations (current ± 30 days), guests, room status, housekeeping tasks, billing drafts, staff schedules, key/lock state snapshots. The sync engine speaks the platform's /sync/v1/pull|push protocol with idempotency keys and per-aggregate conflict policy — never last-write-wins for monetary or inventory state. ONNX models cover housekeeping order optimization, anomaly heuristics, and basic demand smoothing locally; heavier models route to ai-orchestrator-service when online.
What is unique: a real local DB with real conflict resolution and real edge AI — not a connectivity banner.
Desktop stack is fixed: Electron + Vite + React + SQLite (better-sqlite3) + ONNX Runtime Node + electron-builder + electron-updater. Substitutions require an explicit, unanimous ADR.
3.5 Control Plane (platform staff)
A small internal admin surface for Ghasi platform staff to manage tenants, plans, feature flags, theme reviews, and incident response. Lives behind bff-backoffice-service with stricter ABAC. Not a tenant-facing surface and not counted in the four primary surfaces above.
4. Personas
| Persona | Goals | Frustrations | Primary surface | Key KPI |
|---|---|---|---|---|
| Hotel Owner | Visibility into revenue, occupancy, and staff performance across one or more properties; defensible margins; minimal vendor lock-in | Cannot trust the numbers; finance reconciliation takes days; OTA commissions eat margin; cannot benchmark | Desktop dashboards + scheduled reports | Direct-booking ratio; gross profit per available room (GPAR) |
| General Manager | Coordinated operations; rapid response to issues; data to make rate and staffing decisions | Information arrives by phone; manual rate changes; no forecast; staff disputes shifts | Desktop (full backoffice) | Forecast accuracy; alert response time; ADR vs market |
| Front Desk | Fast check-in/out; correct keys; correct folio; handle walk-ins; answer guest questions | Slow PMS, internet drops, paper backlog, double-booked rooms, key-encoder failures | Desktop (reservation + check-in board) | Avg check-in time; walk-in conversion; zero double-booking days |
| Housekeeping Lead | Coordinated room turnover; correct priorities; visibility into delays; clear maintenance escalation | Conflicting priorities from front desk and GM; no language support on existing tools | Desktop (housekeeping board) | Turnover SLA hit-rate; rooms ready before check-in window |
| Housekeeper | Clear task list; correct order; mark rooms ready; report maintenance issues | Paper sheets, retraced steps, conflicting instructions, no Pashto/Dari | Desktop (focused task view) — large touch targets | Rooms cleaned per shift; first-time-right ratio |
| Maintenance | Triaged work orders; parts visibility; preventive tasks not forgotten | Reactive only; no asset history; surprise OOS rooms | Desktop (work-order queue) | MTTR; preventive task completion; OOS hours avoided |
| Finance / Admin | Accurate folios, reconciled cash, audited refunds, currency-aware reports | Cash drawer drift, manual FX, scattered receipts, no audit trail | Desktop (folio + EOD + reports) | End-of-day variance; refund cycle time |
| Chain Operator | Cross-property visibility; standardized operations; benchmarking | Each property runs differently; no aggregated view; consolidating data is manual | Desktop (multi-property switcher) + portal | Cross-property KPI dashboard; standardization compliance score |
| Guest | Find the right room at the right price; book confidently in own language; pay how they want; check in fast | Confusing OTA-branded flows; unclear cancellation rules; payment gateways that fail; no Pashto/Dari support | Tenant booking web/mobile + consumer mobile | Booking completion rate; NPS; check-in time |
| Walk-in Guest | Get a room tonight; pay in cash; minimal paperwork; trust the rate | Suspicion of inflated walk-in rates; no receipt; no record of stay | Desktop (front-desk walk-in flow) | Walk-in conversion; receipt issuance rate |
| Marketing Reviewer | Approve tenant-branded site changes (theme, content blocks, photos) before publish | Slow review queues; no diff view; theme changes break accessibility | Control-plane theme review | Review SLA; reject-and-republish ratio |
Persona-specific journeys are detailed in docs/journeys/01-core-user-journeys.md. Permission models per persona are in docs/07-security-compliance-tenancy.md.
4.1 Operator skill profile
A non-trivial product constraint: the modal backoffice operator in target Phase 0 markets is not a digital native. The desktop app is therefore designed for: large touch targets, generous defaults, undo-everywhere, a "home" affordance always one tap away, voice-friendly labels, no hidden menus for primary tasks, and AI suggestions phrased as "Try this?" rather than as commands.
5. Value Propositions
- Meta-search and direct booking, unified. Discoverability of an OTA, settlement economics of direct — the guest never bounces to a third-party site, and the hotelier keeps the relationship and the margin.
- Offline-first backoffice that actually works offline. Real local SQLite, real conflict resolution per aggregate, real edge AI via ONNX Runtime Node — not just a connectivity banner. The Electron desktop app is the canonical operational surface, designed for daily use without network.
- AI-assisted operations grounded in HITL. Demand forecasting, dynamic pricing suggestions, housekeeping schedule optimization, anomaly detection (suspicious bookings, payment outliers, lock-event anomalies, late-checkout trends), upsell recommendations, and multilingual message drafting — every AI action is suggested, logged, provenance-tagged (
{ model, version, promptId, traceId, reviewedBy?, reviewedAt?, local }), and human-acceptable when the action is irreversible or guest-facing. - Multi-tenant theming without per-tenant forks. Single shared codebase; runtime theming via
theme-config-service; bounded customization that protects accessibility, performance, and security. - RTL/LTR and localization-first. Pashto, Dari, Arabic, English, French day one; locale-aware dates (Gregorian + Hijri + Solar Hijri presentational), currencies, calendars, and numerals across every surface.
- Cost-efficient GCP-native architecture. Cloud Run + Cloud SQL + Pub/Sub + Memorystore sized for small/medium tenants, scaling per-service. No GKE tax, no heavyweight service mesh, no per-room pricing model.
- End-to-end lock integration with pluggable vendors. Adapters for TTLock, Salto, Assa Abloy, and a generic Wiegand/RFID adapter cover the long tail of regional hardware; the key lifecycle is driven by the reservation aggregate's state machine (issue on check-in, update on room change, revoke on early checkout) with vendor-specific failure handling.
- Cash-on-arrival as a first-class payment method. Reconciliation, cash-drawer accounting, and audit trail are core, not workarounds.
- Implementation-grade specs from day one. Every service has 17 standardized docs designed to be fed into AI coding tools (Cursor, Copilot, Claude) without re-explanation.
6. High-Level Feature Catalog
| Domain | Capability | Owning service(s) |
|---|---|---|
| Discovery & Booking | Cross-tenant meta search (list + map) | search-aggregation-service, bff-consumer-service |
| Tenant-branded booking flow (web + mobile) | bff-tenant-booking-service, theme-config-service | |
| Multi-currency presentation, FX snapshot at confirm | pricing-service, billing-service | |
| Pre-arrival messaging, confirmation, receipts | notification-service | |
| PMS | Property + room + room-type catalog, amenities, geo | property-service |
| Reservation lifecycle (book → confirm → check-in → check-out → no-show / cancel) | reservation-service | |
| Walk-ins, group bookings, modifications, splits | reservation-service | |
| Rate & Inventory | Rate plans (BAR, weekly, government, corporate, non-refundable), restrictions (MinLOS / CTA / CTD), seasonal calendars | pricing-service |
| Availability, allocation, overbooking guard, stop-sell | inventory-service | |
| Room state lifecycle (clean / dirty / OOO / OOS) | inventory-service, housekeeping-service | |
| Operations | Housekeeping board + AI-suggested order | housekeeping-service, ai-orchestrator-service |
| Maintenance work orders + asset registry + preventive | maintenance-service | |
| Drag-and-drop room and task boards on the desktop | bff-backoffice-service | |
| Finance & Payments | Folios, charges, taxes, invoices, refunds | billing-service |
| End-of-day reconciliation, cash-drawer accounting | billing-service | |
| Pluggable payments (PayPal, Visa/Debit, cash-on-arrival, MFS) | payment-gateway-service | |
| Sharia-compliant payment policy per tenant | payment-gateway-service | |
| Guest Engagement | Email / SMS / push / WhatsApp / Viber multi-channel notifications | notification-service |
| Guest profiles, preferences, stay history | reservation-service, property-service | |
| Post-stay feedback collection | notification-service | |
| AI-drafted multilingual messages with provenance | ai-orchestrator-service + notification-service | |
| Theming & Configuration | Brand tokens, layout presets, content blocks | theme-config-service |
| Per-tenant policy + content versioning with audit | theme-config-service, tenant-service | |
| Lock & Key | Key issuance, update, revocation tied to reservation state | lock-integration-service, reservation-service |
| Vendor adapters: TTLock, Salto, Assa Abloy, generic Wiegand/RFID | lock-integration-service | |
| Offline key snapshot for the desktop app | lock-integration-service, bff-backoffice-service | |
| Reporting & Analytics | Twelve canonical reports (occupancy, ADR, RevPAR, GPAR, channel mix, payment mix, EOD, audit log, …) | reporting-service |
| Scheduled exports (PDF / CSV) and offline cache | reporting-service | |
| Cross-cutting KPI rollups, time-series, cohorts | analytics-service | |
| AI Services | Demand forecasting + dynamic pricing suggestions | ai-orchestrator-service + pricing-service |
| Housekeeping schedule optimization | ai-orchestrator-service + housekeeping-service | |
| Anomaly detection (bookings, payments, lock events) | ai-orchestrator-service | |
| Upsell recommendations | ai-orchestrator-service + reservation-service | |
| HR-lite | Staff profiles, roles, shifts | staff-service |
| Lightweight time tracking | staff-service | |
| Integrations | Lock vendor adapters (pluggable) | lock-integration-service |
| Payment provider adapters (pluggable) | payment-gateway-service | |
| OTA channel manager (Phase 3+) | reservation-service (channel port) | |
| File storage (photos, invoices, IDs) with signed URLs | file-storage-service |
Some features that competitors highlight are deliberately simplified or absent — see § 11 (Out of Scope).
7. Competitive Positioning
| Capability | Cloudbeds | eZee Absolute | Hotelogix | RoomRaccoon | RMS Cloud | Trivago | Booking.com | Ghasi Melmastoon |
|---|---|---|---|---|---|---|---|---|
| Meta + direct booking unified (no OTA handoff) | No | No | No | No | No | Meta only (handoff) | OTA model | Yes |
| Offline-first backoffice | No | No | No | No | No | N/A | N/A | Yes (Electron + SQLite + sync engine) |
| AI-native ops (forecast, pricing, anomaly, upsell) | Partial add-on | Limited | Limited | Limited | Limited | N/A | Internal only | Native, provenance-tagged, HITL |
| RTL + Pashto/Dari first-class | No | Partial Arabic | No | No | No | Partial | Partial | Yes |
| Multi-tenant theming (no fork) | Limited | Limited | Limited | Limited | Limited | N/A | N/A | Yes (theme-config-service) |
| Low-resource cost fit (per-room USD model) | Per-room USD | Per-room USD | Per-room USD | Per-room USD | Per-room USD | OTA commission | OTA commission | Tiered SaaS sized for SMB |
| Lock integration (multi-vendor) | 1-2 vendors | 1-2 vendors | 1-2 vendors | 1-2 vendors | 1-2 vendors | None | None | Pluggable (TTLock, Salto, Assa Abloy, Wiegand) |
| Tenant customizability without engineering | Limited | Limited | Limited | Limited | Limited | N/A | N/A | Presets + blocks + tokens |
| Cash-on-arrival as first-class | Workaround | Workaround | Workaround | Workaround | Workaround | N/A | Limited | First-class with reconciliation |
| Designed for unreliable network / power | No | No | No | No | No | N/A | N/A | Designed for it |
The defensible wedges are: (a) meta + direct booking unified, (b) genuine offline-first backoffice on Electron with edge AI, (c) Pashto/Dari/RTL leadership, (d) pluggable locks across the long tail of vendors actually present in target markets, (e) AI-native with HITL, and (f) cost fit for SMB independents. No incumbent has more than two of these.
8. Geographic Strategy
| Phase | Geography | Dominant currency | Payment rails | Lock vendor availability | Language priority | Tax model | Regulatory note |
|---|---|---|---|---|---|---|---|
| 0 — Beachhead | Afghanistan | AFN (USD widely used) | Cash-on-arrival dominant; Hawala for cross-border; some PayPal for diaspora; cards rare | TTLock common (mobile-credential), generic Wiegand controllers, mechanical | Pashto + Dari first; English second | Provincial bed-tax + service charge; receipts often hand-written today | No formal hospitality data-protection regime; design to GDPR-class baseline |
| 0 — Beachhead | Tajikistan | TJS (USD/RUB used in tourism) | Cards growing in Dushanbe; cash dominates regions; M-Pesa-like local rails emerging | TTLock + Salto in newer builds; mechanical elsewhere | Dari/Tajik (Persian script variant) first; Russian second; English third | VAT 14% (varies); tourism-zone exemptions | Tourism push from government; data localization not strict |
| 0 — Beachhead | Iran | IRR (USD-pegged informal pricing) | Domestic payment rails (Shaparak/Sadad); international cards effectively unusable; cash + bank transfer | Local + Salto + Assa Abloy in mid-tier; mechanical elsewhere | Persian (Farsi) first; English second; Arabic third | VAT 9%; tourist tax in select cities | Sanctions-aware payment routing; local-only rails by default; CMEK on PII |
| 1 — Near-term regional | Pakistan, Iraq, Egypt secondary cities | PKR, IQD, EGP (USD used) | JazzCash, Easypaisa (PK); Fawry (EG); cash-heavy in IQ | TTLock + Salto + generic | Urdu (PK), Arabic dialects (IQ, EG); English | VAT/GST varies; tourism levies | Country-specific KYC for payments |
| 2 — Mid-term | GCC (UAE, KSA, Oman, Bahrain), South Asia (Nepal, Bangladesh), Sahel + East Africa | AED, SAR, OMR, BHD, NPR, BDT, XOF, KES | Cards mainstream in GCC; M-Pesa, Wave in EA; mobile money in Sahel | Salto + Assa Abloy mainstream in GCC; mixed elsewhere | Arabic + English (GCC); Bengali, Nepali, French, Swahili | VAT 5-15%; tourism dirham/levy in some | UAE PDPL, KSA PDPL, regional data residency |
| 3 — Later | Europe + North America (independents and small chains) | EUR, GBP, USD, CAD | Card-mainstream; Apple/Google Pay; SEPA | Salto + Assa Abloy + Onity + Kaba | EN, FR, DE, ES, IT | VAT/GST country-specific; city tourist tax | GDPR (EU/UK), CCPA (CA), PIPEDA (CA); SOC 2 expected |
Each phase entry condition is documented in docs/roadmap/01-product-roadmap.md and gated by readiness criteria, not calendar dates.
9. Operating Modes
The platform — and especially the Electron desktop app — is designed to remain useful across five operating modes. Each mode has explicit user-facing semantics, sync behavior, and AI behavior.
| Mode | Trigger | What works | What degrades | Sync behavior | AI behavior |
|---|---|---|---|---|---|
| Fully Online | Stable connectivity, all platform services healthy | Everything: meta search, booking, full PMS, full AI, real-time analytics, lock operations | — | Continuous; outbox flushes immediately | Cloud models via ai-orchestrator-service (Vertex AI); HITL on irreversible actions |
| Degraded Online | Connectivity flaky, one or more services slow / down (e.g., payment provider down, lock vendor API down) | Browsing, reservation reads, housekeeping updates, EOD prep | Affected service-specific actions queue (e.g., key-issuance retry, payment retry) | Outbox queues failed mutations with backoff | Cloud models still attempted; fallback to edge models on timeout |
| Fully Offline | No connectivity from the desktop app | Desktop reads from SQLite snapshot: reservations (± 30 days), guests, room status, housekeeping tasks, billing drafts, staff schedules, key/lock state snapshot. New mutations queued in the outbox. Cash-on-arrival check-in/out works end-to-end including key issuance against cached vendor credentials where the lock vendor supports offline issuance | Card payments (degrade to cash-on-arrival or held-for-later); any cross-tenant operation; live AI cloud calls | Outbox accumulates; UI shows clear sync state and pending count | Edge ONNX models only (housekeeping order, anomaly heuristics, basic forecasting smoothing); cloud calls are silently deferred, never silently fabricated |
| Sync Recovery | Connectivity restored after offline period | Background reconciliation: pull server-state delta, push outbox in order, apply per-aggregate conflict resolution; UI surfaces conflicts that need operator decision | Affected screens may briefly show "reconciling" states | Per-aggregate merge rules (never last-write-wins for monetary or inventory state); idempotency keys ensure safe replay | Edge AI continues; cloud AI resumes; provenance tags include local: true → false transition where applicable |
| AI Degraded | ai-orchestrator-service unhealthy, model provider rate-limited, or moderation provider down | All operations work without AI assistance; explicit "AI suggestions unavailable" affordance shown; no auto-applied AI state | AI suggestions, drafted messages, anomaly callouts, dynamic pricing suggestions | Unaffected | UI hides AI affordances or shows "Try again later"; never substitutes a fabricated suggestion |
Sync, conflict resolution, outbox semantics, and idempotency keys are specified in detail in docs/05-api-design.md (sync contract) and docs/04-event-driven-architecture.md.
10. Success Metrics
10.1 North Star
Gross booking volume retained in-platform per tenant per month (in tenant's settlement currency, FX-snapshot at confirm). This single metric captures the product's central wedge: the meta layer drives discovery, and the booking completes in-platform — the hotelier keeps the relationship and the margin.
10.2 Supporting metrics
| Metric | Owner surface / service | Healthy direction | Why it matters |
|---|---|---|---|
| Meta-layer conversion rate (meta search → booking confirmed in-platform) | bff-consumer-service, bff-tenant-booking-service | ↑ | Validates the unified meta + direct value prop |
| Direct-booking share (% of confirmed reservations from direct + meta vs OTA + agent) | reservation-service (channel attribution) | ↑ | Proves we are reducing OTA dependency for tenants |
| Sync conflict rate (conflicts requiring operator decision per 1k synced mutations) | bff-backoffice-service | ↓ | Validates per-aggregate merge rules and offline-first design |
| Sync latency p95 (time from offline mutation to server-side apply once online) | bff-backoffice-service | ↓ | Operational health of the sync engine |
| Key-issuance success rate (per vendor, per attempt) | lock-integration-service | ↑ | Validates the lock-port abstraction and vendor adapters |
| AI suggestion acceptance rate (per surface: pricing, housekeeping, message-drafting, upsell) | ai-orchestrator-service | ↑ over time, with provenance review | Proves AI is useful, not noise; gates Phase 2 capabilities |
| AI HITL bypass attempts (irreversible actions where HITL was required and skipped) | ai-orchestrator-service | = 0 | Compliance + safety guardrail |
| Time-to-check-in (front-desk start → key issued) | desktop app + lock-integration-service | ↓ | Front-line operational quality |
| End-of-day variance (cash drawer expected vs counted) | billing-service | → 0 | Finance trust signal |
| Provider-onboarding time (kickoff → first live booking) | tenant-service + control plane | ↓ | Distribution velocity |
| NPS / guest CSAT (post-stay) | notification-service (collection), analytics-service (rollup) | ↑ | Brand-level signal |
The full metric catalog with computation, owning service, and dashboard placement lives in docs/observability/01-observability.md and analytics-service's bundle.
11. Out of Scope (Initial Spec)
Explicit boundaries — these are not addressed by the current specification set and must not creep into service designs without an ADR:
- Full revenue management beyond suggestions. AI proposes rates; tenants accept or reject. Full automated yield management is deferred until forecast accuracy on real tenant data clears the readiness bar in
docs/08-ai-architecture.md. - Full HR / payroll.
staff-servicecovers profiles, shifts, and lightweight time tracking. Tax, payroll, benefits, performance management, and HRIS integration are out of scope. - Restaurant POS. Out of scope. Phase 3+ may integrate via a thin POS adapter; no in-platform POS is planned.
- Spa / activities / experiences booking. Out of scope; design hooks exist in
pricing-servicefor future ancillary inventory. - OTA channel manager. Phase 3+. The reservation aggregate exposes a
channelport and Phase 0/1 only shipdirect,meta,front-desk, andagentchannels. OTA adapters (Booking.com, Expedia, Agoda) are not in scope now. - Deep accounting integration. Phase 3+. EOD exports (CSV) and per-tenant invoice templates are in scope; QuickBooks / Xero / Zoho Books / SAP B1 connectors are not.
- Loyalty / rewards programs. Out of scope for Phase 0/1;
reservation-servicecarries aloyaltyIdfield reserved for future use. - Native mobile backoffice app. The Electron desktop app is the canonical staff surface. A phone-form-factor staff app is deferred; the consumer mobile app is unrelated to staff workflows.
- Custom HTML in tenant theming. Tenants choose presets and content blocks. Arbitrary HTML/CSS is explicitly disallowed to protect accessibility, performance, and security.
- Self-serve tenant onboarding without human review. Phase 0/1 onboarding is assisted (KYC, payment setup, theme review). Fully self-serve is a Phase 2+ outcome.
- Cross-chain enterprise consolidation. Multi-property is supported (a tenant can own many properties); cross-chain enterprise-grade consolidation (corporate hierarchies, brand families, master-data governance) is deferred.
12. Glossary Refresher
The canonical short glossary lives in the README. It defines the non-negotiable terms used across this overview and every downstream spec: Tenant, Property, Room, Rate Plan, Reservation, Booking, Folio, Channel, Lock Adapter, Key Credential, Backoffice Operator, Guest, Provider Site, PMS, Melmastoon.
For the long-form glossary (including AI provenance, sync vocabulary, payment vocabulary, and lock vocabulary), see docs/standards/NAMING.md.
13. Cross-References
- Architectural realization of every surface and capability:
docs/02-enterprise-architecture.md - Service-by-service breakdown:
SERVICE_INDEX.mdanddocs/03-microservices/README.md - Persona-driven flows including offline + failure paths:
docs/journeys/01-core-user-journeys.md - Phase gating, dependencies, and architectural enablers:
docs/roadmap/01-product-roadmap.md - Engineering conventions every service inherits:
docs/standards/01-engineering-standards.md - Electron desktop app deep spec:
docs/frontend/desktop/06-desktop-app-specification.md