Frontend Journeys — Index

Scope: This folder contains one operational, end-to-end specification per core user journey (J-NN) for Ghasi Melmastoon. Every journey conforms to the same 14-section template (see below) so engineers, designers, QA, and AI coding tools can implement, test, and audit each flow without re-deriving cross-service behaviour.

Predecessor: This set replaces the monolithic ../../journeys/01-core-user-journeys.md. The original file has been converted to a redirect stub for inbound link compatibility for one release.

---

1. Index of journeys

#	Title	Persona	Primary surface	Complexity	Criticality	File
J-01	Discover & Compare on Meta Layer	Guest	Consumer Web/Mobile	M	P0	guest/J-01-discover-and-compare-on-meta-layer.md
J-02	Booking Handoff to Tenant Site	Guest	Consumer -> Tenant Booking	S	P0	guest/J-02-booking-handoff-to-tenant-site.md
J-03	Multi-Step Booking with Cash on Arrival	Guest	Tenant Booking Web/Mobile	L	P0	guest/J-03-multi-step-booking-with-cash-on-arrival.md
J-04	Booking with Card Payment (3DS + FX snapshot)	Guest	Tenant Booking Web/Mobile	L	P0	guest/J-04-booking-with-card-payment.md
J-05	Arrive at Hotel & Check-In	Guest + Front Desk	Electron Desktop	L	P0	guest/J-05-arrive-at-hotel-and-check-in.md
J-06	Stay, Modify, Check-Out	Guest + Front Desk	Electron Desktop	L	P0	guest/J-06-stay-modify-check-out.md
J-07	Walk-In Booking with Cash Deposit (Offline)	Front Desk	Electron Desktop (offline)	L	P0	front-desk/J-07-walk-in-booking-with-cash-deposit-offline.md
J-08	Online Check-In Queue Coordination	Front Desk	Electron Desktop	M	P1	front-desk/J-08-online-check-in-queue-coordination.md
J-09	Mid-Stay Issue: Lock Battery Dies	Front Desk + Maintenance	Electron Desktop	M	P1	front-desk/J-09-mid-stay-issue-lock-battery-dies.md
J-10	Group Booking with Multiple Rooms & Single Folio	Front Desk	Electron Desktop	L	P1	front-desk/J-10-group-booking-multiple-rooms-single-folio.md
J-11	Late Checkout & Folio Dispute	Front Desk + Manager	Electron Desktop	M	P1	front-desk/J-11-late-checkout-and-folio-dispute.md
J-12	End-of-Day Cash Drawer Close	Front Desk + Finance	Electron Desktop	M	P0	front-desk/J-12-end-of-day-cash-drawer-close.md
J-13	Onboard New Tenant (Single Hotel Operator)	Owner	Control Plane + Electron	L	P0	management/J-13-onboard-new-tenant-single-hotel.md
J-14	Onboard Chain (Multi-Property Tenant)	Chain Operator	Control Plane + Electron	L	P1	management/J-14-onboard-chain-multi-property.md
J-15	Configure Dynamic Pricing AI Suggestions	GM	Electron Desktop	M	P1	management/J-15-configure-dynamic-pricing-ai-suggestions.md
J-16	Review Daily Operations Dashboard	GM	Electron Desktop	M	P0	management/J-16-review-daily-operations-dashboard.md
J-17	Run Monthly Tax Report	Finance	Electron Desktop	S	P0	management/J-17-run-monthly-tax-report.md
J-18	Submit Daily Guest Registration to Authority	Receptionist / Admin	Electron Desktop	M	P0	management/J-18-submit-daily-guest-registration-to-authority.md
J-19	Auto-Cleaning on Checkout (Online)	Housekeeping Lead + Housekeeper	Electron Desktop	M	P0	housekeeping/J-19-auto-cleaning-on-checkout-online.md
J-20	Offline Housekeeping Update from Desktop	Housekeeping Lead	Electron Desktop (offline)	M	P0	housekeeping/J-20-offline-housekeeping-update-from-desktop.md
J-21	Mid-Stay Cleaning Request	Guest + Housekeeping	Tenant Booking Mobile + Desktop	S	P1	housekeeping/J-21-mid-stay-cleaning-request.md
J-22	Cleaning Reveals Maintenance Issue	Housekeeper + Maintenance	Electron Desktop	M	P0	housekeeping/J-22-cleaning-reveals-maintenance-issue.md

---

2. The 14-section journey template

Every journey file in this folder MUST conform to this structure. Where a section is genuinely n/a, write "n/a — ".

1. Purpose — Goal as the persona would express it; user outcome named in 1-2 sentences.
2. Persona Context — Persona, surface(s), preconditions, trigger, primary BFF(s).
3. Entry Points — Every way the user can enter this journey (deep link, push, in-app nav, system event).
4. Screen-by-Screen Flow — Numbered list. Each screen carries sub-blocks: Layout text-wire / Components / Offline / AI / Errors / Loading / A11y / RTL / Perf / Telemetry.
5. State Machine — Mermaid stateDiagram-v2.
6. Data Requirements — Endpoints (BFF -> domain), TanStack query keys, IndexedDB / MMKV / SQLite touchpoints, idempotency strategy.
7. AI Behavior — Per AI surface in this journey: purpose, model class, edge vs cloud, HITL UI, provenance UI, fallback.
8. Offline Behavior — What works, what blocks, what the user sees.
9. Error States — Per failure mode: trigger, UX shown, recovery path, telemetry.
10. E2E Test Gates — Named scenarios; cross-link to gates in ../common/10-frontend-testing-strategy.md §3.
11. Performance Requirements — Per-screen budgets, perceived latency targets, network call counts.
12. Accessibility Requirements — Keyboard, focus, screen reader, contrast, touch targets, reduced motion.
13. Telemetry — Frontend frontend.* events + backend domain events emitted.
14. Success Criteria — Concrete, testable assertions for the journey end-to-end.

---

3. Cross-journey invariants (apply to every journey; not repeated per file)

1. Tenant on every request. Every API call carries X-Tenant-Id; every event carries tenantId; every SQLite row carries tenant_id. Zero untenanted reads except the meta-search aggregate.
2. Idempotency on every mutation. All POST/PUT/PATCH carry X-Idempotency-Key (ULID). Desktop outbox uses deterministic keys per pending mutation.
3. Provenance on every AI step. Every AI call attaches aiProvenance = { model, version, promptId, traceId, reviewedBy?, reviewedAt?, local } per ../../08-ai-architecture.md §6.
4. HITL on irreversible AI actions. Anything that mutates guest-facing state (rate change, message send, key issuance, refund) is suggested, never auto-applied, unless tenant has enabled an explicit auto-policy.
5. RTL/LTR by direction, not by locale. Shell honours dir="rtl" for Pashto/Dari/Persian/Arabic. Logical CSS only.
6. Sync-status pill always visible on the Electron desktop. Pending mutations and connectivity state reflected at every step.
7. Audit log is canonical. Every state-changing step emits an entry to the immutable audit log via audit-service subscription on the originating event.
8. Domain canonical. Tenant booking sites live on melmastoon.app; marketing site lives on melmastoon.com. Inbound deep links use the tenant slug subdomain (<slug>.melmastoon.app).

---

4. Cross-cutting catalogs

For deeper reference on the patterns each journey relies on, see:

• ../catalogs/C1-telemetry-event-dictionary.md (P1) — every telemetry event name + properties + sink
• ../catalogs/C2-error-to-ui-matrix.md (P1) — every error code -> UI behaviour
• ../catalogs/C3-empty-loading-error-state-catalog.md (P1)
• ../catalogs/C4-notification-ux-catalog.md (P1)
• ../catalogs/C5-feature-flag-inventory.md (P1)
• ../catalogs/C6-native-api-capability-catalog.md (P1)

For platform / surface specs:

• ../web/, ../mobile/, ../desktop/21-desktop-app-specification.md, ../kiosk/, ../tablet/

---

5. Operating-mode behaviour (master matrix for journey authors)

Each journey runs under one of five operating modes from ../../01-product-overview.md §9. Authors may copy the relevant row into their journey file. Full matrix:

Journey	Fully Online	Degraded Online	Fully Offline	Sync Recovery	AI Degraded
J-01 / J-02	Full	Cached results; banner	PWA cached results; payment blocked	n/a (consumer)	No personalisation; no AI suggestions; flow unaffected
J-03	Full	Hold + payment retry	n/a (consumer flows require online for payment confirm)	n/a	AI transliteration -> manual entry; no blockage
J-04	Full	Card: degrade to cash-on-arrival prompt	Blocked at payment step	n/a	Fraud detection bypassed -> enhanced HITL queue
J-05	Full	ID OCR retries	ID OCR uses edge ONNX; lock issuance via offline-cert; mobile-key SMS queued	Provisional credentials reconciled	Manual ID entry only
J-06	Full	Payment retries	Charges queued; key revoke via offline-cert	Outbox flush in folio order	n/a
J-07	Equivalent to J-05 walk-in	Same	Primary mode; fully supported	Reservation arbitration; conflict UX	Manual transliteration
J-08	Full	SSE retries	Reads from SQLite snapshot; mobile-key invites queued	Outbox flush; lock vendor reconciliation	No upsell suggestions
J-09	Full	Vendor retries	Local fallback (backup card pool)	Vendor revoke reconciliation	n/a
J-10	Full	Inventory hold retries	Walk-in path (J-07) for groups	Multi-aggregate conflict UX	n/a
J-11	Full	n/a	Credit note local; refund queued	Outbox flush	n/a
J-12	Full	n/a	Settlement local; EOD report from SQLite	Outbox flush	n/a
J-13 / J-14	Full (online required)	Tenant onboarding requires online	n/a	n/a	Theme palette suggestion -> manual
J-15	Full	Suggestions cached	Edge model produces smoothed forecast	n/a	"Suggestions unavailable today"
J-16	Full	Stale-projection badge	First paint from SQLite; SSE upgrades on reconnect	n/a	AI insight tile hidden
J-17 / J-18	Full	Generation queued	Generation from SQLite; submission queued	Outbox flush; submission retry	n/a
J-19	Full	AI routing -> manual	n/a (housekeepers usually share property)	n/a	Manual assignment only
J-20	n/a	n/a	Primary mode	Conflict UX	n/a
J-21	Full	Notification retries	Reads only on guest side	Outbox flush	n/a
J-22	Full	Maintenance creation retries	Local; reaccommodation deferred until online	Reaccommodation surfaces in Sync Center	n/a

---

6. AI HITL pattern (canonical card; reused across journeys)

Every AI suggestion in the platform implements the same surface contract:

+-------------------------------------------------------------+
|  AI Suggestion Card                                          |
|  +---------------------------------------------------------+|
|  | Suggestion text                                          ||
|  | Rationale: <1-line summary>                              ||
|  | Confidence: <bar>                                        ||
|  | Provenance: <model>@<version> . prompt:<id> . trace:<id> ||
|  +---------------------------------------------------------+|
|  [ Accept ]   [ Modify ]   [ Reject ]   [ Why this? ]       |
+-------------------------------------------------------------+

• Accept records reviewedBy + reviewedAt and applies the action.
• Modify opens an editable view; on save, persists the edited value with provenance preserved.
• Reject records the reason (free-text optional) and does not apply.
• Why this? opens a panel with the model, the prompt, and the contributing data points.

Irreversible actions (rate change, message send, key issuance, refund) MUST require Accept/Modify; auto-apply is disallowed unless tenant policy explicitly enables it.

---

References

• ../../11-testing-strategy-qa.md
• ../../08-ai-architecture.md
• ../../09-lock-and-key-integration.md
• ../../10-payments-architecture.md
• ../common/10-frontend-testing-strategy.md