07 — Epics & User Stories (Jira-Ready, Full End-State)

Companion: 01 Product Overview · 02 Enterprise Architecture · 03 Microservices Catalog · 04 Event-Driven Architecture · 05 API Design · 06 Data Models · 07 Security, Compliance & Multi-Tenancy · 08 AI Architecture · 09 Lock & Key Integration · 10 Payments · 11 Frontend Web/Mobile · 12 Desktop · 14 Core User Journeys · Definition of Done

This document is the canonical, end-state product backlog for Ghasi Melmastoon. It is implementation-grade and Jira-importable. Stories cite the services, frontends, and journeys they realize so that engineering, QA, and AI coding tools (Cursor, Claude, Copilot) can execute them without re-deriving cross-service behaviour.

Stack reminder (non-negotiable). Desktop is Electron (Node 20 main + Chromium renderer + Vite + React + better-sqlite3 + ONNX Runtime Node). Cloud is Google Cloud Platform (Cloud Run, Cloud SQL, Pub/Sub, Memorystore, Cloud Storage, Secret Manager, Vertex AI). There is no Tauri, no AWS, no Azure. Substitutions require an explicit unanimous ADR.

1. Purpose & How To Read

1.1 What is an "epic" here

An epic (EP-MEL-NN) is a multi-sprint capability bundle that delivers an end-to-end user-visible outcome. An epic is not a service, not a release, and not a feature flag. It groups the stories required for a single value proposition (e.g., "tenant onboarding & configuration") to ship and remain coherent across web, mobile, desktop, BFFs, and platform services.

An epic is done when:

Every story under it is accepted.
The end-to-end journey(s) it serves are green in docs/journeys/01-core-user-journeys.md.
Telemetry from §10 of the product overview is wired and emitting.
The epic's owner has signed off in services/<owning-service>/SERVICE_READINESS.md.

1.2 What is a "story" here

A story (US-MEL-NNNN) is an INVEST-shaped engineering deliverable: Independent, Negotiable, Valuable, Estimable, Small, Testable. Every story carries:

Field	Meaning
ID	`US-MEL-NNNN`, four-digit zero-padded, allocated in epic order.
Title	`As a <persona>, I want <outcome>, so that <value>.`
Acceptance Criteria	2 – 5 Given/When/Then clauses that QA executes verbatim.
Services	Owning + participating microservices from `03-microservices/README.md`.
Frontend Surfaces	Consumer Web · Consumer Mobile · Tenant Booking Web/Mobile · Electron Desktop · Control Plane.
DoD refs	Sections of `standards/DEFINITION_OF_DONE.md` that apply (Universal · Data · API · Events · Security · AI · Frontend · Observability).
Test types	Unit · Integration · Contract · E2E · Offline · AI-eval · Perf · Security (subset per story).
Complexity	S (≤ 2 dev-days), M (≤ 5 dev-days), L (≤ 12 dev-days). XL is forbidden — split.

1.3 Naming & ID rules

Epic IDs: EP-MEL-01 … EP-MEL-20. Twenty hard cap; new epic requires ADR.
Story IDs: US-MEL-NNNN, monotonic across all epics. Never reused. Never renumbered.
Saga IDs: SAGA-MEL-<NAME> from docs/04-event-driven-architecture.md.
Journey IDs: J-NN from docs/journeys/01-core-user-journeys.md.

1.4 Personas (canonical short list)

Hotel Owner · General Manager · Front Desk · Housekeeping Lead · Housekeeper · Maintenance Tech · Finance / Admin · Chain Operator · Guest · Walk-In Guest · Marketing Reviewer · Platform Admin · Compliance Officer. Full descriptions in 01-product-overview.md §4.

1.5 Cross-cutting acceptance (echoed per epic, never per story)

Every story implicitly inherits these acceptance gates from DEFINITION_OF_DONE.md:

Tenant context propagated (X-Tenant-Id + JWT tid cross-checked); RLS active on every table.
Idempotency key on every write (HTTP and outbox).
AI calls only via ai-orchestrator-service; AIProvenance attached; HITL on irreversible actions.
i18n strings extracted; LTR + RTL parity; logical CSS only; axe-clean (WCAG 2.2 AA).
Outbox + inbox pattern on every event; no PII in event payloads.
Money as bigint micro-units; FX-snapshot frozen at confirm.
Telemetry: trace_id, tenant_id, request_id on every log line.

If a story violates one of these, it is not done, even if the AC list passes.

2. Epic Index

Epic	Title	Primary persona	Services involved	Complexity	Priority	Wave
EP-MEL-01	Tenant Onboarding & Configuration	Hotel Owner	iam · tenant · property · theme-config · staff · file-storage · notification	XL	P0	R1
EP-MEL-02	Consumer Meta Search Layer	Guest	search-aggregation · bff-consumer · property · pricing · theme-config	L	P0	R1
EP-MEL-03	Tenant-Branded Booking Experience (Web + Mobile)	Guest	bff-tenant-booking · reservation · pricing · inventory · payment-gateway · notification · theme-config	XL	P0	R1
EP-MEL-04	Reservation Lifecycle (Quote → Confirm → Stay → Checkout)	Front Desk · Guest	reservation · inventory · pricing · billing · payment-gateway · notification	XL	P0	R1
EP-MEL-05	Payment Gateway with Cash on Arrival, MFS, Cards	Finance · Guest	payment-gateway · billing · reservation · notification	L	P0	R1
EP-MEL-06	Front-Desk Operations on Electron Desktop	Front Desk	bff-backoffice · reservation · billing · payment-gateway · lock-integration · notification · file-storage	XL	P0	R1
EP-MEL-07	Housekeeping Coordination	Housekeeping Lead · Housekeeper	housekeeping · maintenance · reservation · ai-orchestrator · notification · staff	L	P0	R1
EP-MEL-08	Maintenance & Asset Management	Maintenance Tech	maintenance · housekeeping · file-storage · notification	M	P1	R2
EP-MEL-09	Lock & Key Integration with Offline Issuance	Front Desk · Guest	lock-integration · reservation · notification · ai-orchestrator	XL	P0	R1
EP-MEL-10	Offline-First Desktop with Sync Engine	Front Desk · Housekeeping	bff-backoffice · every domain service · ai-orchestrator (edge)	XL	P0	R1
EP-MEL-11	AI-Assisted Operations	GM · Front Desk · Housekeeping	ai-orchestrator · pricing · reservation · housekeeping · maintenance · notification · billing	XL	P1	R2
EP-MEL-12	Multi-Tenant Theming & Per-Tenant Booking Flow Config	Owner · Marketing Reviewer	theme-config · file-storage · bff-consumer · bff-tenant-booking · notification	L	P0	R1
EP-MEL-13	Reporting (Operational, Financial, Regulatory)	GM · Finance · Compliance	reporting · analytics · reservation · billing · payment-gateway · file-storage · notification	L	P0	R1
EP-MEL-14	Analytics Pipeline (Events → BigQuery → Dashboards → AI Signals)	GM · Owner	analytics · all event publishers · ai-orchestrator	L	P1	R2
EP-MEL-15	Multi-Channel Notification (Email, SMS, WhatsApp, Push)	Guest · Front Desk	notification · ai-orchestrator · file-storage · bff-*	L	P0	R1
EP-MEL-16	File Storage with Signed URLs, Virus Scan, Image Optimization	Owner · Marketing Reviewer · Guest	file-storage · every consumer service	M	P0	R1
EP-MEL-17	Identity, Auth, Multi-Tenant RBAC, MFA, SSO, Device Binding	Owner · GM · Front Desk	iam · tenant · staff · bff-backoffice · notification	XL	P0	R1
EP-MEL-18	Multi-Language & RTL/LTR	All	theme-config · notification · all frontends	L	P0	R1
EP-MEL-19	Compliance & Regulatory (Tax, KYC, Audit Logs)	Compliance · Finance	pricing · billing · reporting · analytics · iam	L	P0	R1
EP-MEL-20	Observability, Reliability, Cost Controls	Platform · SRE	every service	L	P0	R1

Story counts. 161 total stories (US-MEL-0001 … US-MEL-0161). Aggregate effort estimate in §23. Phasing into release waves R1/R2/R3 in §24.

3. EP-MEL-01 — Tenant Onboarding & Configuration

Outcome. A hotel owner self-signs up, creates a tenant, configures a property and rooms, invites staff, customises the brand theme, configures the booking flow, previews the public site, and publishes it. From signup to a guest-bookable site in under 90 minutes with marketing-review gating only the publish step.

Primary owner. tenant-service (org lifecycle), with iam-service, property-service, theme-config-service, staff-service, file-storage-service, notification-service participating.

Journeys realised. J-13 (Onboard New Tenant — Single Hotel Operator), J-14 (Onboard Chain — Multi-Property Tenant).

Cross-cutting AC for this epic. All onboarding writes are idempotent; tenant context is established before any property/room write; tenant deletion in trial is reversible for 30 days; theme assets uploaded via file-storage-service carry tenant_id prefix.

As a prospective Hotel Owner, I want to sign up with my email and phone, so that I can start a 30-day trial without contacting sales.

AC1 — Given I submit a valid email + phone + password (≥ 12 chars, breached-check passes), When I confirm both OTPs, Then an iam-service User is created and a Tenant(plan=trial, status=pending_kyc) exists.
AC2 — Given the email is already registered, When I submit, Then I receive MELMASTOON.IAM.EMAIL_TAKEN and a passwordless sign-in link is offered.
AC3 — Given I am on a sanctioned-country IP (per OFAC list snapshot), When I attempt signup, Then the request is denied with MELMASTOON.IAM.GEO_RESTRICTED, an audit entry written, and no tenant created.
Services. iam-service, tenant-service, notification-service (OTP).
Frontend. Tenant Booking Web (Owner Portal sub-route) · Consumer Mobile (link only).
DoD refs. Universal · Data · API · Events · Security · Observability.
Test types. Unit (password policy, OTP rate-limit) · Integration (Postgres + Redis OTP store) · Contract (Pact: notification.email.send.v1) · E2E (signup happy path) · Security (anti-enumeration, brute-force).
Complexity. M.

US-MEL-0002 — Create primary tenant, pin home region, accept ToS

As a newly-signed-up Owner, I want to create my tenant, choose home region, and accept ToS, so that my data residency is locked from day one.

AC1 — Given a verified user without a tenant, When I POST /api/v1/tenants with {name, slug?, homeRegion} and an Idempotency-Key, Then a tenant is created with status=trial, region pinned to homeRegion, and RLS tenant_id context activates immediately.
AC2 — Given I omit slug, When the tenant is created, Then the system generates one from name, ensures uniqueness, and returns it.
AC3 — Given my home region is unavailable for my country code, When I post, Then I receive MELMASTOON.TENANT.REGION_UNSUPPORTED with the supported list.
AC4 — Given I accept ToS vX, When the tenant is created, Then tenant.tos_accepted_at and tenant.tos_version=X are recorded.
Services. tenant-service, iam-service.
Frontend. Owner Portal (Tenant Booking Web subdomain).
DoD refs. Universal · Data · API · Events · Security.
Test types. Unit (slug generator) · Integration (RLS bootstrap) · Contract · E2E.
Complexity. M.

US-MEL-0003 — Add the first property with geo, address, amenities

As an Owner, I want to add my hotel's primary property with address, geo coordinates, and amenities, so that it can later be searchable on the meta layer.

AC1 — Given I submit {name, address, geo: {lat, lng}, country, city, amenities[], starRating?}, When I post to /api/v1/properties, Then a Property aggregate is created scoped to my tenant_id.
AC2 — Given the geo coordinates are outside my country, When validated, Then I receive MELMASTOON.PROPERTY.GEO_OUT_OF_COUNTRY and the property is rejected.
AC3 — Given I provide ≤ 25 amenities from the canonical list, When the property is saved, Then all amenities map to canonical IDs (translatable in any locale).
Services. property-service, tenant-service.
Frontend. Owner Portal · Electron Desktop (post-onboarding).
DoD refs. Universal · Data · API · Events.
Test types. Unit (geo validation) · Integration · Contract.
Complexity. M.

US-MEL-0004 — Define room types and individual rooms

As an Owner, I want to define room types (king, twin, suite, family) and each individual room with floor and number, so that inventory and housekeeping can be modelled per room.

AC1 — Given a property exists, When I create a RoomType with {code, name, baseOccupancy, maxOccupancy, bedConfig}, Then it is persisted under the property.
AC2 — Given a RoomType exists, When I bulk-create rooms [{number, floor, view?, accessibility?}, ...], Then each Room is created with lifecycle state clean and tenant-scoped.
AC3 — Given I attempt to create a room with a duplicate (property_id, number), Then I receive MELMASTOON.PROPERTY.ROOM_DUPLICATE.
Services. property-service, inventory-service (downstream for default allocation).
Frontend. Owner Portal.
DoD refs. Universal · Data · API · Events.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0005 — Invite staff and assign roles

As an Owner, I want to invite my front-desk, housekeeping, finance, and GM staff with a single role, so that they can sign in to the desktop app on day one.

AC1 — Given I post [{email, phone?, role}], When invites are queued, Then each invitee receives an email + SMS with a single-use link valid for 7 days.
AC2 — Given a staff member opens the link, When they set a password and complete OTP, Then an iam-service User + Membership(tenantId, role) exists.
AC3 — Given the role is front_desk, When the user signs in on the desktop app, Then they see only the front-desk shell (no finance, no settings).
AC4 — Given I revoke an invite before acceptance, Then the link returns 410 and an audit entry exists.
Services. iam-service, tenant-service, staff-service, notification-service.
Frontend. Owner Portal · Email + SMS deep links · Electron Desktop.
DoD refs. Universal · Data · API · Events · Security.
Test types. Unit · Integration · Contract · E2E.
Complexity. M.

US-MEL-0006 — Customise theme tokens (logo, colours, typography)

As an Owner, I want to upload my logo and pick brand colours + typography, so that my booking site reflects my brand.

AC1 — Given I upload a logo (PNG/SVG ≤ 2 MB), When the upload succeeds, Then file-storage-service returns a CDN URL and the asset is virus-scanned within 5 s.
AC2 — Given I pick a primary colour from the colour-picker, When saved, Then theme-config-service validates contrast ratio against AAA-large-text (≥ 4.5:1 for normal text on the chosen background).
AC3 — Given my chosen contrast fails, Then the UI surfaces a warning with auto-suggested adjustments and blocks publish until accepted with override.
Services. theme-config-service, file-storage-service.
Frontend. Owner Portal · Live preview iframe.
DoD refs. Universal · Data · API · Events · Frontend.
Test types. Unit (contrast checker) · Integration · Contract · A11y.
Complexity. M.

US-MEL-0007 — Choose layout preset and content blocks

As an Owner, I want to pick a layout preset (modern, classic, minimal) and customise hero, about, policies, FAQ blocks, so that my site has my voice without writing HTML.

AC1 — Given I select a preset, When saved, Then the active theme version increments and a draft is queued for marketing review.
AC2 — Given I edit a content block in three locales (Pashto, Dari, English), When I save, Then all three versions are persisted with locale discriminator.
AC3 — Given I attempt to save raw HTML in a block, Then the API sanitises it via the allowlist and returns the sanitised string.
Services. theme-config-service.
Frontend. Owner Portal · Block editor.
DoD refs. Universal · Data · API · Frontend.
Test types. Unit (HTML sanitiser) · Integration · Contract · A11y · i18n.
Complexity. M.

US-MEL-0008 — Configure booking-flow rules per tenant

As an Owner, I want to configure the booking flow (currency display, allowed payment methods, cancellation policies, deposit %), so that my site reflects my commercial rules.

AC1 — Given I enable cash_on_arrival, card, paypal, When saved, Then bff-tenant-booking-service exposes only those methods at quote time.
AC2 — Given I set a 24h-free-cancel rule, When a guest books, Then the policy is materialised onto the reservation with version pinning.
AC3 — Given I require 30% deposit on card bookings, When a card-paying guest confirms, Then payment-gateway-service captures only 30% and stores intent for the balance.
Services. tenant-service, pricing-service, payment-gateway-service.
Frontend. Owner Portal.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract.
Complexity. L.

US-MEL-0009 — Preview the public booking site as a guest

As an Owner, I want to preview my booking site exactly as a guest would see it, so that I can validate the brand and flow before publishing.

AC1 — Given I click "Preview", When the preview opens, Then it renders against my draft theme and config behind a signed preview URL valid for 24 h.
AC2 — Given I am previewing, When I attempt to complete a booking, Then the system uses a sandboxed payment-gateway-service adapter and never charges real money.
AC3 — Given preview-mode mutates state, Then mutations are flagged preview=true and excluded from analytics.
Services. bff-tenant-booking-service, theme-config-service, payment-gateway-service (sandbox adapter).
Frontend. Owner Portal · Preview iframe.
DoD refs. Universal · API · Frontend.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0010 — Submit theme + config for marketing review

As an Owner, I want to submit my draft for review, so that Ghasi marketing can confirm a11y and brand-safety before publish.

AC1 — Given I click "Submit for review", When the request is accepted, Then a ThemeReview aggregate is created with status=pending and a Marketing Reviewer is notified.
AC2 — Given a Marketing Reviewer rejects with comments, When I revisit the draft, Then I see the reviewer's comments inline anchored to the offending blocks.
AC3 — Given review is approved, When I click "Publish", Then the draft becomes the live theme version and a theme.published.v1 event fires.
Services. theme-config-service, notification-service, iam-service (reviewer role).
Frontend. Owner Portal · Control Plane (reviewer surface).
DoD refs. Universal · API · Events · Security · Frontend.
Test types. Unit · Integration · Contract · E2E.
Complexity. M.

US-MEL-0011 — Publish to make the site live

As an Owner, I want to publish my approved theme and config, so that my site is bookable on my subdomain.

AC1 — Given an approved draft, When I publish, Then DNS-routed traffic to {slug}.melmastoon.app and any custom domain serves the live theme within 60 s.
AC2 — Given publish succeeds, When search-aggregation-service indexes the listing, Then it appears in meta search within 5 minutes.
AC3 — Given I roll back to a prior version, When I confirm rollback, Then the previous version is live within 60 s and a theme.rolledback.v1 event fires.
Services. theme-config-service, search-aggregation-service, bff-tenant-booking-service, bff-consumer-service.
Frontend. Owner Portal.
DoD refs. Universal · API · Events · Observability.
Test types. Unit · Integration · Contract · E2E · Perf (publish latency).
Complexity. M.

US-MEL-0012 — Onboarding progress checklist with resume

As an Owner, I want a single checklist that tracks my onboarding progress, so that I can pause and resume without losing context.

AC1 — Given I am mid-onboarding, When I sign out, Then I can sign back in any time and the checklist shows me the next pending step.
AC2 — Given I have completed all steps but not published, Then the checklist shows "Ready to publish" with a single CTA.
AC3 — Given an Owner is stalled for > 7 days, When the daily job runs, Then a templated reminder email + SMS is queued via notification-service.
Services. tenant-service, notification-service.
Frontend. Owner Portal · Email reminders.
DoD refs. Universal · API · Frontend.
Test types. Unit · Integration · E2E.
Complexity. S.

4. EP-MEL-02 — Consumer Meta Search Layer

Outcome. A guest discovers hotels across all published tenants through a Trivago-style web/mobile experience with list and map views, applies filters (price band, amenities, rating, distance), compares up to three, and hands off into the chosen tenant's booking flow without leaving the platform.

Primary owner. search-aggregation-service + bff-consumer-service, with property-service, pricing-service, theme-config-service participating.

Journeys realised. J-01 (Discover & Compare on Meta Layer), J-02 (Booking Handoff to Tenant Site).

Cross-cutting AC for this epic. Cross-tenant reads are restricted to cross_tenant_searchable=true fields. PII, payment data, key credentials, and operational secrets are never indexed. Every search is logged with query_id for ranking-tuning.

US-MEL-0013 — Search by city + dates + guests

As a Guest, I want to search hotels by city, check-in/out dates, and guest count, so that I see properties that can host me on the dates I need.

AC1 — Given I submit {city, checkIn, checkOut, adults, children}, When results return, Then I see properties that have at least one bookable rate for the given dates within 1.5 s p95.
AC2 — Given dates are in the past or checkOut <= checkIn, Then the API returns MELMASTOON.SEARCH.INVALID_DATES.
AC3 — Given the city is ambiguous (multiple matches across countries), Then results are grouped by country with a banner.
Services. search-aggregation-service, bff-consumer-service, inventory-service (live availability check, cached).
Frontend. Consumer Web · Consumer Mobile.
DoD refs. Universal · API · Frontend · Observability.
Test types. Unit · Integration · Contract · E2E · Perf.
Complexity. L.

US-MEL-0014 — Filter results by price band, amenities, rating

As a Guest, I want to filter results by price band, amenities, and star rating, so that I narrow to options that fit my budget and needs.

AC1 — Given results loaded, When I select {priceMin, priceMax, amenities: [parking, wifi, halal_kitchen, prayer_room], minRating}, Then results re-render in ≤ 800 ms p95 with only matching properties.
AC2 — Given my filters yield zero results, Then the UI shows a "no matches" panel with one-tap relax-filter suggestions.
AC3 — Given I clear all filters, Then the original result set is restored without re-querying the server (client cache hit).
Services. search-aggregation-service, bff-consumer-service.
Frontend. Consumer Web · Consumer Mobile.
DoD refs. Universal · API · Frontend.
Test types. Unit · Integration · E2E · Perf.
Complexity. M.

US-MEL-0015 — Switch between list and map views (Leaflet)

As a Guest, I want to switch between a list view and a map view, so that I can see properties relative to where I want to go.

AC1 — Given I am on list view, When I tap "Map", Then the map renders with a pin per result and clusters above 25 pins per viewport.
AC2 — Given I tap a pin, Then a popover shows hotel name, photo, min/max price for my dates, and a "Book" CTA.
AC3 — Given I pan or zoom, Then results refetch within the new viewport bounds debounced at 400 ms.
Services. search-aggregation-service, bff-consumer-service.
Frontend. Consumer Web (Leaflet) · Consumer Mobile (react-native-maps).
DoD refs. Universal · API · Frontend · A11y.
Test types. Unit · Integration · E2E · A11y · Visual regression.
Complexity. L.

US-MEL-0016 — Compare up to three properties side-by-side

As a Guest, I want to mark up to three properties and compare them side-by-side, so that I can decide more confidently.

AC1 — Given I tap "Compare" on three properties, When I open the comparison panel, Then I see price, amenities, distance to a chosen POI, rating, and cancellation policy in a column-per-property layout.
AC2 — Given I attempt to add a fourth, Then the UI prompts me to remove one first.
AC3 — Given I tap "Book" on one column, Then I am handed off to that tenant's booking flow with my dates and guest count carried in the URL.
Services. bff-consumer-service, pricing-service, theme-config-service.
Frontend. Consumer Web · Consumer Mobile.
DoD refs. Universal · API · Frontend.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0017 — Show price band & availability summary per result

As a Guest, I want each result card to show min/max price for my dates and a quick availability summary, so that I can decide without opening every property.

AC1 — Given results render, Then each card shows {minPriceDisplayed, maxPriceDisplayed, currency, lastQuoteAt} and a nightsAvailable count.
AC2 — Given prices are computed in tenant currency, When I switch the display currency, Then prices convert via the latest FX-snapshot from pricing-service and the converted amounts carry an "≈" prefix.
AC3 — Given a property has no availability for any of the requested dates, Then it is filtered out of results before render (not greyed out).
Services. search-aggregation-service, pricing-service, inventory-service.
Frontend. Consumer Web · Consumer Mobile.
DoD refs. Universal · API · Frontend.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0018 — Hand off into tenant booking flow with state preserved

As a Guest, I want to enter the tenant's booking site without losing my dates and filters, so that the experience feels continuous.

AC1 — Given I tap "Book" from a result, When I land on the tenant booking site, Then dates, guests, and the selected room type pre-fill from the URL parameters.
AC2 — Given the tenant theme loads, Then the page is fully themed within 800 ms p95 (server-rendered theme hydration).
AC3 — Given I navigate back to meta, Then my prior search and filters are restored from the session.
Services. bff-consumer-service, bff-tenant-booking-service, theme-config-service.
Frontend. Consumer Web · Consumer Mobile · Tenant Booking Web/Mobile.
DoD refs. Universal · API · Frontend.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0019 — Localise meta layer to RTL languages with currency conversion

As a Guest browsing in Pashto/Dari/Persian/Arabic, I want the meta layer fully RTL with locale-aware dates, numerals, and currencies, so that I never feel like a translation afterthought.

AC1 — Given my locale is ps-AF, When the page loads, Then dir=rtl is set, all CSS is logical, and Pashto strings render from the bundle.
AC2 — Given I switch numeral system to Arabic-Indic, Then all numbers render in Arabic-Indic except machine-precision fields (price input boxes stay European for safety).
AC3 — Given my currency is AFN but I prefer USD display, When I toggle, Then USD prices appear with FX-snapshot timestamp in a tooltip.
Services. theme-config-service, bff-consumer-service, pricing-service.
Frontend. Consumer Web · Consumer Mobile.
DoD refs. Universal · Frontend · A11y · i18n.
Test types. Unit · Visual (RTL screenshot) · A11y · i18n cross-locale.
Complexity. L.

US-MEL-0020 — Anonymous favourites & recent searches

As a Guest, I want to favourite properties and see my recent searches without creating an account, so that I can come back later.

AC1 — Given I tap the heart on a property, Then it is stored in localStorage (web) / AsyncStorage (mobile) keyed by an anonymous device ID.
AC2 — Given I revisit, Then my favourites list persists across sessions for 90 days.
AC3 — Given I sign in later, Then I can opt to migrate favourites to my account.
Services. bff-consumer-service (read-through enrichment only).
Frontend. Consumer Web · Consumer Mobile.
DoD refs. Universal · Frontend · Security (no PII).
Test types. Unit · Integration · E2E.
Complexity. S.

5. EP-MEL-03 — Tenant-Branded Booking Experience (Web + Mobile)

Outcome. A guest, having landed on the tenant booking site (from meta or directly), completes a multi-step booking with full multi-language and multi-currency support, picks a payment method (cash-on-arrival, card, PayPal, MFS), and receives confirmation across email + SMS + WhatsApp.

Primary owner. bff-tenant-booking-service, with reservation-service, pricing-service, inventory-service, payment-gateway-service, notification-service, theme-config-service participating.

Journeys realised. J-03 (Multi-Step Booking with Cash on Arrival), J-04 (Booking with Card Payment + 3DS + FX snapshot).

Cross-cutting AC for this epic. Tenant theme loads before any booking interaction; quote TTLs honoured; FX snapshot frozen at confirm; idempotency on all booking writes.

US-MEL-0021 — Browse rooms and rate plans on the tenant site

As a Guest, I want to browse the tenant's rooms and rate plans in a themed UI, so that I can compare options before picking one.

AC1 — Given I land on the tenant site, Then within 1 s the theme is applied, hero block renders, and within 2 s the date/guest selector is interactive.
AC2 — Given I pick dates and guest count, When results render, Then room types are listed with per-rate-plan price, photos, and amenity badges.
AC3 — Given a room type is sold out for my dates, Then the card shows a "Sold out — try other dates" affordance with the closest available date.
Services. bff-tenant-booking-service, property-service, pricing-service, inventory-service, theme-config-service.
Frontend. Tenant Booking Web · Tenant Booking Mobile.
DoD refs. Universal · API · Frontend · Perf.
Test types. Unit · Integration · E2E · Perf · A11y.
Complexity. L.

US-MEL-0022 — Adjust room count, dates, guests, options (+/–)

As a Guest, I want to fluently adjust room count, dates, guests, and options with +/– controls, so that I can refine without losing my selection.

AC1 — Given I increment guests beyond room max occupancy, Then the UI surfaces "exceeds room capacity" with a one-tap upgrade suggestion.
AC2 — Given I change dates, When the new dates query returns, Then the rate refreshes and a banner shows "rate changed from X to Y".
AC3 — Given I add an extra bed option, Then the price updates within 300 ms (client cache, server-validated on confirm).
Services. bff-tenant-booking-service, pricing-service.
Frontend. Tenant Booking Web · Tenant Booking Mobile.
DoD refs. Universal · API · Frontend.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0023 — Capture special requests and arrival time

As a Guest, I want to leave special requests (early check-in, accessible room, halal breakfast) and an estimated arrival time, so that the hotel can prepare.

AC1 — Given I add a special request, When the booking confirms, Then the request is attached to the reservation aggregate and surfaced on the front-desk arrival board.
AC2 — Given I submit a request in Pashto, Then the text is preserved verbatim and a translation hint is queued via ai-orchestrator-service for the front desk.
AC3 — Given my requested arrival is past midnight, Then the UI confirms the actual check-in date with a "this will be on day X" prompt.
Services. reservation-service, ai-orchestrator-service (translation hint, async, HITL).
Frontend. Tenant Booking Web · Tenant Booking Mobile.
DoD refs. Universal · API · AI · Frontend.
Test types. Unit · Integration · Contract · E2E · AI eval.
Complexity. M.

US-MEL-0024 — Pick payment method and confirm

As a Guest, I want to pick from cash-on-arrival, card, PayPal, or MFS based on what the tenant allows, so that I can pay how I prefer.

AC1 — Given the tenant allows [card, cash_on_arrival], Then only those two appear at checkout.
AC2 — Given I choose card and complete 3DS successfully, When capture succeeds, Then the reservation transitions held → confirmed and a reservation.confirmed.v1 event fires within 500 ms p95 of capture webhook.
AC3 — Given I choose cash-on-arrival, When I confirm, Then the reservation transitions to confirmed_pending_payment with deposit rules applied per tenant config.
AC4 — Given payment fails, Then the reservation rolls back to the held state with a 5-minute extended TTL and the UI shows the failure with retry CTA.
Services. bff-tenant-booking-service, reservation-service, payment-gateway-service, inventory-service.
Frontend. Tenant Booking Web · Tenant Booking Mobile.
DoD refs. Universal · API · Events · Security · Frontend.
Test types. Unit · Integration · Contract · E2E · Security (PCI scope).
Complexity. L.

US-MEL-0025 — Multi-currency display with FX snapshot

As a Guest, I want to see prices in my preferred currency with a clear snapshot timestamp, so that I trust the conversion and the final charge.

AC1 — Given I switch display currency, Then all prices render with FX-snapshot from pricing-service (≤ 4 hours old).
AC2 — Given I confirm a booking in display currency USD when settlement is AFN, Then the FX rate is frozen onto the reservation and the folio records both chargeCurrency and settlementCurrency with the snapshot.
AC3 — Given the FX snapshot is older than 24 hours, Then the booking flow blocks confirm and triggers a fresh fetch.
Services. pricing-service, billing-service, bff-tenant-booking-service.
Frontend. Tenant Booking Web · Tenant Booking Mobile.
DoD refs. Universal · API · Frontend · Compliance.
Test types. Unit (FX snapshot freezing) · Integration · Contract.
Complexity. M.

US-MEL-0026 — Multi-language booking flow (Pashto/Dari/Persian/Arabic/EN/FR/Tajik)

As a Guest, I want the entire booking flow in my language, so that I am not forced into English.

AC1 — Given my browser is ps-AF, Then the entire flow renders in Pashto, RTL, with locale-aware date/number formatting.
AC2 — Given I switch locale mid-flow, Then form values persist and labels swap; my entered text is preserved verbatim.
AC3 — Given I confirm a booking, Then confirmation messages (email/SMS/WhatsApp) are sent in my chosen locale.
Services. bff-tenant-booking-service, notification-service, theme-config-service.
Frontend. Tenant Booking Web · Tenant Booking Mobile.
DoD refs. Universal · Frontend · A11y · i18n.
Test types. Unit · Visual (RTL) · i18n.
Complexity. L.

US-MEL-0027 — Confirmation page with itinerary and add-to-calendar

As a Guest, I want a confirmation page with my full itinerary and a one-tap add-to-calendar, so that I have everything I need without searching email.

AC1 — Given booking is confirmed, When the page renders, Then I see reservation ID, dates, room, total, payment summary, cancellation policy, and arrival instructions.
AC2 — Given I tap "Add to calendar", Then an .ics file downloads (web) or my OS calendar prompt opens (mobile).
AC3 — Given I refresh the confirmation page, Then the data is fetched by reservation ID with idempotent reads (no duplicate side-effects).
Services. reservation-service, bff-tenant-booking-service, notification-service.
Frontend. Tenant Booking Web · Tenant Booking Mobile.
DoD refs. Universal · API · Frontend.
Test types. Unit · E2E.
Complexity. S.

US-MEL-0028 — Resend confirmation across channels

As a Guest, I want to resend my confirmation by email, SMS, or WhatsApp at any time, so that I can recover if I lose the original.

AC1 — Given I look up my reservation by ID + email, Then I can request a resend on any allowed channel.
AC2 — Given the channel is rate-limited (≥ 3 resends/24 h), Then I receive MELMASTOON.NOTIFICATION.RATE_LIMIT.
AC3 — Given the resend is successful, Then an audit entry records {reservationId, channel, requestedBy: guest, timestamp}.
Services. notification-service, reservation-service.
Frontend. Tenant Booking Web · Tenant Booking Mobile.
DoD refs. Universal · API · Security · Observability.
Test types. Unit · Integration · Contract.
Complexity. S.

US-MEL-0029 — Booking funnel telemetry for analytics

As a Product / Analytics owner, I want every booking step instrumented, so that drop-off and conversion can be analysed by channel and locale.

AC1 — Given any booking-flow page renders, Then a frontend.booking.step.entered event is emitted with {step, locale, currency, deviceClass}.
AC2 — Given the booking confirms, Then reservation.confirmed.v1 carries {channel: meta|direct|...}.
AC3 — Given a guest abandons mid-flow, Then an inactivity timer fires frontend.booking.abandoned after 30 minutes.
Services. bff-tenant-booking-service, analytics-service, reservation-service.
Frontend. Tenant Booking Web · Tenant Booking Mobile.
DoD refs. Universal · Events · Observability.
Test types. Unit · Integration · Contract.
Complexity. S.

6. EP-MEL-04 — Reservation Lifecycle (Quote → Confirm → Stay → Checkout)

Outcome. The full lifecycle of a reservation aggregate, from initial price quote, hold, confirm, modifications, cancellations, upsells, mid-stay edits, and checkout, with deterministic state transitions and saga compensation on every failure.

Primary owner. reservation-service (saga orchestrator), with inventory-service, pricing-service, billing-service, payment-gateway-service, notification-service participating.

Journeys realised. J-03, J-04, J-05, J-06, J-07, J-10, J-11.

Cross-cutting AC for this epic. Every reservation transition emits a versioned event; outbox + inbox enforced; sagas tested for happy + every compensation; idempotency keys on every command; aggregate guards against cross-tenant references.

US-MEL-0030 — Generate price quote with TTL

As a Guest, I want to receive a precise price quote that I can rely on for a few minutes, so that the price doesn't change while I check out.

AC1 — Given I request a quote for {property, roomType, ratePlan, dates, guests, addons}, Then the quote returns within 400 ms p95 with quoteId, total, currency, expiresAt = now + 10m.
AC2 — Given the quote is expired at confirm, Then confirm fails with MELMASTOON.RESERVATION.QUOTE_EXPIRED and a fresh quote is auto-issued.
AC3 — Given rates change between quote and confirm but the quote is still valid, Then the original quoted price is honoured.
Services. pricing-service, reservation-service.
Frontend. Tenant Booking Web/Mobile · Electron Desktop (walk-in).
DoD refs. Universal · API · Events.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0031 — Place an inventory hold for a quote

As a Reservation Service consumer, I want to place a 10-minute hold on inventory at quote time, so that the room cannot be double-booked while a guest checks out.

AC1 — Given a valid quote, When I call /holds, Then inventory-service decrements available count and creates a Hold(quoteId, expiresAt).
AC2 — Given a hold expires unconfirmed, Then inventory restores within 60 s and a inventory.hold.expired.v1 event fires.
AC3 — Given the hold is confirmed by reservation-service, Then the hold becomes permanent allocation and the same room cannot be sold by another flow.
Services. inventory-service, reservation-service.
Frontend. N/A (backend).
DoD refs. Universal · API · Events · Data.
Test types. Unit · Integration · Contract · Concurrency (race tests).
Complexity. L.

US-MEL-0032 — Confirm a reservation with payment outcome

As a Reservation Service, I want to atomically confirm a reservation when payment succeeds, so that we never sell a room without recording payment intent.

AC1 — Given payment captures successfully, When the saga proceeds, Then the reservation transitions held → confirmed within 500 ms and reservation.confirmed.v1 is published.
AC2 — Given payment fails, When the compensation runs, Then the hold is released, the quote is invalidated, and reservation.confirm_failed.v1 carries the failure reason.
AC3 — Given the saga is retried due to a transient downstream failure, Then the idempotency key prevents duplicate confirmations.
Services. reservation-service, payment-gateway-service, inventory-service, billing-service.
Frontend. N/A.
DoD refs. Universal · Events · Security.
Test types. Unit · Integration · Contract · Saga (happy + compensation) · Chaos.
Complexity. L.

US-MEL-0033 — Modify reservation dates within policy

As a Guest or Front-Desk staff, I want to modify reservation dates within the policy window, so that I can adjust without cancelling.

AC1 — Given the modification policy permits the change, When I PATCH /reservations/:id/dates, Then new inventory is held, prices recomputed, and folio adjusted with delta charges.
AC2 — Given the new dates have no inventory, Then the request fails with MELMASTOON.RESERVATION.NO_INVENTORY and the original dates remain intact.
AC3 — Given the modification incurs a fee per tenant config, Then the fee is added to the folio and reservation.modified.v1 carries feeApplied.
Services. reservation-service, inventory-service, pricing-service, billing-service.
Frontend. Tenant Booking Web/Mobile · Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · Contract · E2E.
Complexity. L.

US-MEL-0034 — Cancel reservation with policy enforcement

As a Guest or Front-Desk staff, I want to cancel a reservation with the correct refund per policy, so that the guest experience is fair and the books match.

AC1 — Given the cancellation falls within free-cancel window, When cancelled, Then a full refund is initiated and inventory is released within 60 s.
AC2 — Given the cancellation is outside the free window, Then the configured penalty is charged and only the remainder is refunded.
AC3 — Given the saga compensation needs to revoke an issued key, Then lock-integration-service revoke is called and the key state transitions to revoked.
Services. reservation-service, inventory-service, payment-gateway-service, billing-service, lock-integration-service, notification-service.
Frontend. Tenant Booking Web/Mobile · Electron Desktop.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract · Saga (compensation) · E2E.
Complexity. L.

US-MEL-0035 — Upsell offers (early check-in, late check-out, room upgrade)

As a Guest, I want to be offered relevant upsells at confirmation and pre-arrival, so that I can enhance my stay if it makes sense.

AC1 — Given the guest has confirmed, Then an upsell selector is shown on the confirmation page with available add-ons.
AC2 — Given the guest accepts an upsell, Then the folio is updated and the inventory holds are extended/upgraded as needed.
AC3 — Given the upsell suggestion is AI-generated, Then AIProvenance is attached and the offer is HITL-reviewed before display in tenants where AI auto-display is off.
Services. reservation-service, pricing-service, inventory-service, ai-orchestrator-service.
Frontend. Tenant Booking Web/Mobile · Email/SMS reminder.
DoD refs. Universal · API · AI · Events.
Test types. Unit · Integration · Contract · AI eval.
Complexity. M.

US-MEL-0036 — Check-in flow (front desk + guest mobile self-check-in)

As a Front-Desk staff member, I want a streamlined check-in flow that issues keys, captures ID, and updates folio, so that check-in takes < 3 minutes for a returning guest.

AC1 — Given the reservation is in confirmed status and dates are today, When I check in, Then the state transitions confirmed → checked_in, a key is issued via lock-integration-service, and the folio opens.
AC2 — Given ID capture is required (regulatory), Then the front desk captures ID via file-storage-service and the storage path is referenced in the reservation.
AC3 — Given lock issuance fails, Then the check-in queues a retry, the room is marked "key pending", and the front desk is notified.
Services. reservation-service, lock-integration-service, file-storage-service, billing-service.
Frontend. Electron Desktop · Tenant Booking Mobile (self-check-in).
DoD refs. Universal · API · Events · Security · Compliance.
Test types. Unit · Integration · Contract · E2E · Offline.
Complexity. L.

US-MEL-0037 — Mid-stay folio updates (charges, incidentals)

As a Front-Desk staff member, I want to add incidentals and charges to a guest's folio mid-stay, so that the bill at checkout is accurate.

AC1 — Given a checked-in reservation, When I add a charge {description, amount, taxCode}, Then the folio updates, an event fires, and the new total is reflected on the guest's account.
AC2 — Given I add a charge offline (Electron desktop), Then the charge is queued in the outbox and applied on sync.
AC3 — Given a charge is voided within 24 h with manager approval, Then the void is recorded as a separate ledger entry (no destructive deletes).
Services. billing-service, reservation-service, bff-backoffice-service.
Frontend. Electron Desktop.
DoD refs. Universal · Data · API · Events · Offline.
Test types. Unit · Integration · Contract · Offline.
Complexity. M.

US-MEL-0038 — Checkout flow with folio close and key revoke

As a Front-Desk staff member, I want to check guests out, close the folio, and revoke keys, so that the room is freed and accounted for.

AC1 — Given the reservation is checked_in, When I check out, Then the folio closes, settlement is computed, and the room transitions occupied → dirty.
AC2 — Given the folio has an outstanding balance and policy allows post-pay, Then the balance is settled per the chosen payment method.
AC3 — Given any key credential is active, Then lock-integration-service revokes all credentials and key.revoked.v1 is published.
Services. reservation-service, billing-service, lock-integration-service, housekeeping-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract · E2E.
Complexity. L.

US-MEL-0039 — Walk-in booking from front desk

As a Front-Desk staff member, I want to create a walk-in booking, so that I can serve guests who arrive without a reservation.

AC1 — Given I open the walk-in flow, When I choose room, dates, guest, payment, Then the reservation is created in checked_in state directly with cash or card capture.
AC2 — Given I am offline, When I create a walk-in, Then the reservation is staged in SQLite with a deterministic outbox key and reconciles on sync.
AC3 — Given I capture cash deposit offline, Then the cash drawer reflects the deposit and a paper receipt prints from the local thermal printer.
Services. reservation-service, billing-service, payment-gateway-service, lock-integration-service, bff-backoffice-service.
Frontend. Electron Desktop.
DoD refs. Universal · Data · API · Events · Offline · Frontend.
Test types. Unit · Integration · Offline · E2E.
Complexity. L.

US-MEL-0040 — No-show handling

As a General Manager, I want the system to flag no-shows automatically and apply the no-show policy, so that revenue is captured per contract.

AC1 — Given a confirmed reservation has no check-in by the cutoff (configurable, e.g., 02:00 next day), Then the system transitions to no_show, applies the no-show charge, and releases inventory if policy allows.
AC2 — Given the policy is "first night charge", Then the folio reflects only one night and the rest is voided.
AC3 — Given a guest later disputes the no-show, Then a manager-approved override can reset the state and reverse the charge with full audit trail.
Services. reservation-service, billing-service, inventory-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Compliance.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0041 — Group booking with single folio across multiple rooms

As a Front-Desk staff member, I want to create a group booking across multiple rooms tied to a single folio, so that the group leader pays once.

AC1 — Given I create a group booking with n rooms, Then n reservations are created linked by groupId, and a single folio aggregates all charges.
AC2 — Given one room within the group cancels, Then the per-room cancellation policy applies; the rest of the group remains intact.
AC3 — Given the group leader pays the consolidated folio, Then payment is applied across the linked reservations proportionally.
Services. reservation-service, billing-service, inventory-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · E2E.
Complexity. L.

7. EP-MEL-05 — Payment Gateway with Cash on Arrival, MFS, Cards

Outcome. A pluggable payment-gateway service that supports cash-on-arrival (cash drawer + reconciliation), card (Stripe/Adyen-style adapter), PayPal, and Mobile Financial Services (MFS) — with multi-currency, refunds, partial captures, chargebacks, and PCI-scope isolation.

Primary owner. payment-gateway-service, with billing-service, reservation-service, notification-service participating.

Journeys realised. J-04, J-05 (deposit at check-in), J-07 (walk-in cash), J-12 (EOD cash close).

Cross-cutting AC for this epic. No PAN ever leaves PCI scope; webhooks signature-verified; idempotent capture/refund; FX snapshot frozen onto every PaymentIntent.

US-MEL-0042 — Card payment with 3DS

As a Guest, I want to pay by card with 3DS strong-customer-authentication, so that my payment is secure.

AC1 — Given I submit card details via the hosted vendor iframe, Then the card token returns to the browser and the PAN never touches our backend.
AC2 — Given 3DS is required, When I complete the challenge, Then capture proceeds; otherwise the intent stays in requires_action.
AC3 — Given capture succeeds, Then payment.captured.v1 fires and the reservation saga proceeds.
Services. payment-gateway-service, reservation-service, billing-service.
Frontend. Tenant Booking Web/Mobile.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract · E2E · Security (PCI scope).
Complexity. L.

US-MEL-0043 — PayPal payment

As a Guest, I want to pay with PayPal, so that I don't need to share my card details.

AC1 — Given I tap "Pay with PayPal", When I authorise in the PayPal sandbox/live, Then capture proceeds and the intent transitions to succeeded.
AC2 — Given the PayPal callback signature is invalid, Then the request is rejected and the intent stays in requires_action with audit entry.
AC3 — Given the user abandons, Then the intent expires after 15 minutes and the hold releases.
Services. payment-gateway-service, reservation-service.
Frontend. Tenant Booking Web/Mobile.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract · Security.
Complexity. M.

US-MEL-0044 — Cash-on-arrival with deposit policy

As a Tenant, I want to accept cash-on-arrival with a configurable deposit, so that I serve cash-economy guests without losing protection.

AC1 — Given the tenant requires 0% deposit, When the guest confirms, Then the reservation transitions to confirmed_pending_payment and arrives on the front-desk arrival board.
AC2 — Given the tenant requires X% deposit, When the guest confirms, Then the deposit is captured by the chosen method and the rest is recorded as due_at_arrival.
AC3 — Given the guest never arrives, Then the no-show flow (US-MEL-0040) applies.
Services. payment-gateway-service, reservation-service, billing-service.
Frontend. Tenant Booking Web/Mobile · Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0045 — MFS (Mobile Financial Services) adapters

As a Guest in PK / TJ / EG / EA markets, I want to pay through JazzCash / Easypaisa / Fawry / M-Pesa, so that I can use my preferred local rail.

AC1 — Given the tenant has enabled an MFS provider, When I pick it, Then the provider's flow is invoked and I receive a confirmation/SMS code.
AC2 — Given I confirm the SMS code, Then the intent captures and the reservation proceeds.
AC3 — Given the provider is down, Then the UI shows the outage and offers fallback methods.
Services. payment-gateway-service, notification-service.
Frontend. Tenant Booking Web/Mobile.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract · Mock-vendor tests.
Complexity. L.

US-MEL-0046 — Refund (full and partial)

As a Finance/Admin, I want to issue full or partial refunds, so that disputes and policy refunds are handled correctly.

AC1 — Given I refund full, When the request is accepted, Then the original PaymentIntent is refunded via the same rail and the folio reflects a credit.
AC2 — Given I refund partial, Then the remaining amount stays as a successful capture.
AC3 — Given a refund attempt fails (rail rejection), Then the failure reason is captured and the manual reconciliation queue is updated.
Services. payment-gateway-service, billing-service, reservation-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0047 — Chargeback handling

As a Finance/Admin, I want chargeback notifications to land in a queue with evidence-collection support, so that I can dispute fraudulent or erroneous chargebacks.

AC1 — Given the card processor reports a chargeback, When the webhook is verified, Then a Chargeback aggregate is created and the folio is flagged.
AC2 — Given I attach evidence (booking proof, ID scans, communications), Then they are uploaded to file-storage-service and the dispute payload is submitted.
AC3 — Given the dispute outcome arrives, Then the folio updates accordingly and an audit trail is preserved.
Services. payment-gateway-service, billing-service, file-storage-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0048 — Idempotent webhook processing

As a Platform engineer, I want all payment webhooks to be idempotent and signature-verified, so that retries never double-charge or double-refund.

AC1 — Given the same webhook is delivered twice, When processed, Then only one state transition occurs.
AC2 — Given the webhook signature fails verification, Then the request is rejected and a security alert fires.
AC3 — Given the webhook arrives out-of-order (e.g., refund before capture confirmation), Then the inbox holds the event and processes after dependencies resolve.
Services. payment-gateway-service.
Frontend. N/A.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract · Chaos.
Complexity. M.

US-MEL-0049 — End-of-day cash drawer reconciliation

As a Finance/Admin, I want to close the cash drawer at end-of-day with expected vs counted vs variance, so that my books match.

AC1 — Given the day has cash transactions, When I open EOD close, Then I see expected cash (sum of cash transactions minus refunds) and a counted-input.
AC2 — Given I submit counted cash, Then variance is computed and captured; variances > X% trigger a manager-approval requirement.
AC3 — Given I close the drawer, Then an eod.cash_drawer.closed.v1 event fires and the next day's drawer is auto-opened.
Services. billing-service, payment-gateway-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Compliance.
Test types. Unit · Integration · E2E.
Complexity. M.

8. EP-MEL-06 — Front-Desk Operations on Electron Desktop

Outcome. A front-desk operator can complete every operational task — arrivals, walk-ins, check-ins, mid-stay edits, checkouts, cash drawer, receipts — entirely on the Electron desktop, online or offline, with deterministic sync and no data loss.

Primary owner. bff-backoffice-service + Electron desktop app, with reservation-service, billing-service, payment-gateway-service, lock-integration-service, notification-service, file-storage-service participating.

Journeys realised. J-05, J-06, J-07, J-08, J-10, J-11, J-12.

Cross-cutting AC for this epic. Every action available offline; sync engine drains outbox FIFO; SQLite WAL + crash safety; thermal-printer integration; CSP/contextBridge sandboxing.

US-MEL-0050 — Arrivals board with today's expected guests

As a Front-Desk staff member, I want a board showing today's arrivals with status (expected, on-the-way, arrived), so that I can prepare keys and rooms.

AC1 — Given today has 25 arrivals, Then the board lists them sorted by arrival time, with quick filters (VIP, group, special-request).
AC2 — Given I tap an arrival, Then I see reservation summary, payment status, special requests, and a one-tap check-in.
AC3 — Given I am offline, Then the board renders from SQLite with the most recent sync timestamp shown.
Services. reservation-service, bff-backoffice-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Frontend · Offline.
Test types. Unit · Integration · Offline · E2E.
Complexity. M.

US-MEL-0051 — One-tap check-in with key issuance

As a Front-Desk staff member, I want to complete a check-in with a single confirmation, so that I keep wait times minimal.

AC1 — Given the guest is at the desk, When I tap "Check in", Then the reservation transitions to checked_in and a key is issued via lock-integration-service within 5 s p95.
AC2 — Given lock issuance fails, Then the check-in succeeds, the front-desk gets a "key pending" alert, and a retry is queued.
AC3 — Given I am offline, Then check-in proceeds against the SQLite snapshot, and a key.issued_offline.v1 is staged for the encoder vendor on reconnect.
Services. reservation-service, lock-integration-service, billing-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Offline · Security.
Test types. Unit · Integration · Offline · E2E.
Complexity. L.

US-MEL-0052 — Mid-stay reservation modifications

As a Front-Desk staff member, I want to modify a guest's reservation mid-stay (extend, room change, guest count), so that I can accommodate changes.

AC1 — Given a checked-in guest wants to extend, When I add nights, Then inventory is rechecked, prices updated, folio adjusted, and key validity extended via lock vendor.
AC2 — Given I move the guest to a different room, Then the old room transitions to dirty, the new room is allocated, and the key is updated/reissued.
AC3 — Given I am offline, Then the modification is queued and will be reconciled with conflict policy on sync.
Services. reservation-service, inventory-service, lock-integration-service, billing-service, housekeeping-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Offline.
Test types. Unit · Integration · Offline · E2E.
Complexity. L.

US-MEL-0053 — Checkout flow with receipt printing

As a Front-Desk staff member, I want to check a guest out and print a receipt from the local thermal printer, so that the guest leaves with a paper record.

AC1 — Given a checked-in guest is at the desk, When I tap checkout, Then the folio closes, payment settles, the key is revoked, and a thermal receipt prints in the guest's chosen locale.
AC2 — Given the printer is offline, Then the receipt is queued and re-prints on next available printer or PDF-emailed.
AC3 — Given any step fails, Then the checkout is paused at that step with a clear retry/skip option.
Services. reservation-service, billing-service, payment-gateway-service, lock-integration-service, notification-service.
Frontend. Electron Desktop · Local thermal printer.
DoD refs. Universal · API · Events · Frontend · Offline.
Test types. Unit · Integration · E2E · Offline.
Complexity. L.

US-MEL-0054 — Cash drawer open/close with audit

As a Front-Desk staff member, I want to open and close my cash drawer at shift start and end, so that my shift is auditable.

AC1 — Given I start a shift, When I open the drawer, Then I record the opening float and a shift.started.v1 event fires.
AC2 — Given I close the drawer, Then I record counted cash; variance is computed and stored.
AC3 — Given my closing variance exceeds X%, Then my supervisor must approve the close before the drawer can reopen.
Services. billing-service, staff-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Compliance.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0055 — Receipts as PDF in folio history

As a Guest or Finance/Admin, I want every receipt archived as a PDF in the folio history, so that I can re-download anytime.

AC1 — Given a folio is closed, Then a PDF is generated in tenant locale and stored in file-storage-service with a signed URL.
AC2 — Given I request a re-download, Then a new signed URL is issued (TTL = 24 h).
AC3 — Given the tenant requires a fiscal QR code (e.g., Iran), Then the PDF includes the QR per regulatory rules.
Services. billing-service, file-storage-service, reporting-service.
Frontend. Electron Desktop · Tenant Booking Mobile.
DoD refs. Universal · API · Compliance.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0056 — Manager override pin for sensitive actions

As a General Manager, I want my PIN to authorise variance overrides, refunds, and policy bypasses, so that front-desk actions stay accountable.

AC1 — Given a front-desk attempts a manager-only action, When prompted, Then my PIN is captured and validated against iam-service.
AC2 — Given my PIN is wrong 3 times, Then the override is locked for 15 minutes and an alert fires.
AC3 — Given I authorise an override, Then the audit log records {action, overrideBy, timestamp, reason}.
Services. iam-service, bff-backoffice-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Security · Observability.
Test types. Unit · Integration · Security.
Complexity. S.

US-MEL-0057 — Quick guest lookup by phone, email, name, ID

As a Front-Desk staff member, I want to find a guest by any identifier in under a second, so that I can serve walk-up enquiries fast.

AC1 — Given I type a partial phone, Then matching guests appear within 200 ms from the local SQLite FTS5 index.
AC2 — Given I tap a result, Then I see all reservations (past, present, future) for that guest within tenant.
AC3 — Given I am offline, Then the search uses the local index and shows the last sync timestamp.
Services. reservation-service, bff-backoffice-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Frontend · Offline.
Test types. Unit · Integration · Offline.
Complexity. M.

US-MEL-0058 — Shift handover summary

As a Front-Desk staff member, I want a one-screen summary at end-of-shift showing arrivals handled, walk-ins, check-outs, cash, pending tasks, so that the next shift starts informed.

AC1 — Given I tap "Handover", Then a summary appears with counts and outstanding items.
AC2 — Given I add notes, Then the next shift sees them at sign-on.
AC3 — Given the summary is generated offline, Then it syncs as a shift.handover.recorded.v1 event.
Services. staff-service, reservation-service, billing-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Offline.
Test types. Unit · Integration · Offline.
Complexity. S.

9. EP-MEL-07 — Housekeeping Coordination

Outcome. Housekeeping tasks are created automatically from reservation events, AI-suggested ordering balances staff load, status flips cascade to inventory, and maintenance escalations route to the maintenance service. Mobile and desktop hand-offs are seamless, online or offline.

Primary owner. housekeeping-service, with maintenance-service, reservation-service, ai-orchestrator-service, notification-service, staff-service participating.

Journeys realised. J-19 (Auto-cleaning on checkout), J-20 (Offline housekeeping update), J-21 (Mid-stay request), J-22 (Maintenance escalation).

Cross-cutting AC for this epic. Tasks scoped to property + tenant; AI suggestions provenance-tagged; offline-first updates with conflict policy.

US-MEL-0059 — Auto-create cleaning task on checkout

As a Housekeeping Lead, I want a cleaning task to appear automatically when a guest checks out, so that rooms are turned over fast.

AC1 — Given a reservation.checked_out.v1 fires, Then a HousekeepingTask(type=turnover, priority=high) is created within 2 s.
AC2 — Given the next arrival for that room is within 4 hours, Then the priority is escalated to urgent.
AC3 — Given the task is created, Then the room transitions dirty → cleaning_queue in the inventory.
Services. housekeeping-service, reservation-service, inventory-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0060 — Drag-and-drop housekeeping board

As a Housekeeping Lead, I want a drag-and-drop board to assign tasks to staff and reorder priorities, so that I can coordinate a shift visually.

AC1 — Given the board renders, When I drag a task to a staff column, Then the assignment persists and the staff member is notified.
AC2 — Given I reorder within a column, Then the new order is reflected for the staff member.
AC3 — Given I am offline, Then drags persist locally and reconcile on sync with last-write-wins for assignment ownership only.
Services. housekeeping-service, staff-service, notification-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Frontend · Offline.
Test types. Unit · Integration · Offline · E2E · A11y.
Complexity. L.

US-MEL-0061 — AI-suggested cleaning order

As a Housekeeping Lead, I want AI to suggest an optimal task order considering room proximity, arrival times, and staff capacity, so that turnover SLAs are hit more often.

AC1 — Given I tap "Suggest order", When the AI returns, Then the suggestion is rendered as a preview with AIProvenance and a clear "Try this?" CTA.
AC2 — Given I accept, Then the order applies and a housekeeping.order.ai_accepted.v1 event fires.
AC3 — Given I am offline, Then an ONNX edge model produces a degraded-but-valid suggestion with local: true.
Services. ai-orchestrator-service, housekeeping-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · AI · Frontend · Offline.
Test types. Unit · Integration · AI eval · Offline.
Complexity. L.

US-MEL-0062 — Housekeeper kiosk mode

As a Housekeeper, I want a focused kiosk mode that shows only my next task with large touch targets, so that I can work fast in the field.

AC1 — Given I sign into kiosk mode on a tablet/laptop, Then I see only my assigned tasks one at a time.
AC2 — Given I mark a task in-progress, Then the room transitions to cleaning and the lead's board updates.
AC3 — Given I mark done, Then the room transitions to clean and is available for inventory.
Services. housekeeping-service, inventory-service.
Frontend. Electron Desktop (kiosk sub-mode).
DoD refs. Universal · API · Frontend · A11y.
Test types. Unit · Integration · A11y.
Complexity. M.

US-MEL-0063 — Escalate to maintenance from housekeeping

As a Housekeeper, I want to flag maintenance issues during cleaning, so that they're triaged without delay.

AC1 — Given I find an issue, When I tap "Report maintenance", Then I capture severity, photo (via webcam or attached file), and notes.
AC2 — Given the report submits, Then a maintenance.ticket.created.v1 event fires and the room may transition to OOO if severity is high.
AC3 — Given I am offline, Then the ticket and photo are queued and uploaded when bandwidth permits.
Services. housekeeping-service, maintenance-service, file-storage-service, inventory-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Offline.
Test types. Unit · Integration · Offline · E2E.
Complexity. M.

US-MEL-0064 — Status board with SLA timer

As a Housekeeping Lead, I want a status board with a turnover SLA timer for every room, so that I see at-risk rooms before guests arrive.

AC1 — Given a room has an arrival in 2 hours and is still dirty, Then the SLA timer turns amber.
AC2 — Given the SLA breaches, Then the timer turns red and an alert fires to the lead and on-shift staff.
AC3 — Given the room is marked clean, Then the timer disappears and the SLA is recorded.
Services. housekeeping-service, analytics-service (rollup).
Frontend. Electron Desktop.
DoD refs. Universal · API · Frontend · Observability.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0065 — Mid-stay cleaning request from guest

As a Guest, I want to request mid-stay cleaning from the tenant booking site (mobile), so that I can plan my day around it.

AC1 — Given I am a checked-in guest, When I request cleaning at a chosen time window, Then a task is created with source=guest_request.
AC2 — Given the task is unassigned within the SLA, Then the lead is notified.
AC3 — Given I cancel my request, Then the task is removed and the lead notified.
Services. housekeeping-service, reservation-service, bff-tenant-booking-service.
Frontend. Tenant Booking Mobile · Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · Contract · E2E.
Complexity. M.

US-MEL-0066 — Multi-language housekeeper instructions

As a Housekeeper whose primary language is Pashto/Dari, I want instructions and task descriptions in my language, so that I don't misinterpret them.

AC1 — Given my user locale is ps-AF, Then the entire kiosk UI and all task descriptions are in Pashto.
AC2 — Given an English description is provided by the lead, Then an AI-translated Pashto version is offered with AIProvenance.
AC3 — Given I have no internet, Then the strings come from the local i18n bundle.
Services. housekeeping-service, ai-orchestrator-service, theme-config-service.
Frontend. Electron Desktop.
DoD refs. Universal · Frontend · AI · i18n.
Test types. Unit · i18n · A11y.
Complexity. M.

10. EP-MEL-08 — Maintenance & Asset Management

Outcome. A lightweight asset registry plus a work-order system that supports preventive schedules, vendor coordination, parts tracking, and seamless escalation from housekeeping.

Primary owner. maintenance-service, with housekeeping-service, file-storage-service, notification-service participating.

US-MEL-0067 — Create work order with severity, room, asset

As a Maintenance Tech, I want to create a work order tied to a room and asset, so that issues are tracked end-to-end.

AC1 — Given I create a work order with {room, asset?, severity, description, attachments?}, Then it is persisted with status=open and a ticket number.
AC2 — Given the severity is critical, Then the room is auto-transitioned to OOO and a manager is notified.
AC3 — Given I attach a photo, Then it uploads to file-storage-service and is referenced.
Services. maintenance-service, inventory-service, file-storage-service, notification-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0068 — Assign and triage work orders

As a Maintenance Tech / Lead, I want to assign work orders by skill and priority, so that the right tech handles the right job.

AC1 — Given a queue of open tickets, When I assign one to a tech, Then the assignee is notified and the ticket transitions to assigned.
AC2 — Given the assigned tech declines, Then the ticket returns to the queue with a decline reason.
AC3 — Given an SLA is configured, Then breaching tickets are highlighted.
Services. maintenance-service, staff-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0069 — Close work orders with parts and labor

As a Maintenance Tech, I want to close a ticket with parts and labor entries, so that maintenance cost is captured.

AC1 — Given I close a ticket, When I add {parts: [{sku, qty, unitCost}], laborMinutes}, Then the cost summary is computed and persisted.
AC2 — Given the room was OOO, Then the room transitions back to dirty for housekeeping and inventory updates.
AC3 — Given I close offline, Then the close event is queued and applied on sync.
Services. maintenance-service, inventory-service, housekeeping-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Offline.
Test types. Unit · Integration · Offline.
Complexity. M.

US-MEL-0070 — Preventive maintenance schedule

As a Maintenance Lead, I want to schedule recurring preventive checks per asset, so that breakdowns are reduced.

AC1 — Given I configure a schedule (e.g., AC service every 90 days), Then tickets are auto-generated 7 days before the due date.
AC2 — Given a preventive ticket is overdue by 7 days, Then the asset is flagged and the lead is notified.
AC3 — Given I disable a schedule, Then future tickets are not generated, but existing tickets remain.
Services. maintenance-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0071 — Vendor coordination for outsourced repairs

As a Maintenance Lead, I want to attach external vendor info and quotes to a work order, so that outsourced repairs are tracked.

AC1 — Given I add a vendor, When I attach a quote PDF, Then the file is stored and the ticket reflects vendor and quote.
AC2 — Given the vendor invoices, Then I can mark the ticket "vendor invoiced" and the cost is added to the ticket.
AC3 — Given the work is complete, Then I close the ticket and the vendor is recorded for future reference.
Services. maintenance-service, file-storage-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0072 — Asset registry with lifecycle status

As a Maintenance Lead, I want an asset registry per property with lifecycle (active, retired) and warranty info, so that I have a single source for what we own.

AC1 — Given I add an asset {name, room?, type, serial, purchaseDate, warrantyEnd}, Then it is persisted under the property.
AC2 — Given an asset is retired, Then active tickets reference the asset but no new tickets can target it.
AC3 — Given the warranty is expiring in 30 days, Then the lead is notified.
Services. maintenance-service.
Frontend. Electron Desktop.
DoD refs. Universal · API.
Test types. Unit · Integration.
Complexity. M.

11. EP-MEL-09 — Lock & Key Integration with Offline Issuance

Outcome. A vendor-agnostic lock service issues, updates, revokes mobile/RFID/PIN keys across TTLock, Salto, Assa Abloy, and generic Wiegand encoders. Offline issuance via the Electron desktop + on-prem encoder is a first-class flow.

Primary owner. lock-integration-service, with reservation-service, notification-service, ai-orchestrator-service (anomaly) participating.

Journeys realised. J-05 (check-in key issuance), J-06 (lost-key revoke), J-09 (lock battery dies), J-07 (offline walk-in key).

Cross-cutting AC for this epic. Vendor secrets only in Secret Manager; per-vendor failure handling via ACL; key lifecycle driven by reservation aggregate state.

US-MEL-0073 — Issue mobile-key invite at check-in

As a Front-Desk staff member, I want to issue a mobile-key invite by SMS/WhatsApp at check-in, so that the guest unlocks via their phone.

AC1 — Given the lock vendor supports mobile keys, When I issue, Then the guest receives an invite link and the credential is created with validFrom and validUntil from reservation.
AC2 — Given the guest declines or doesn't activate, Then a fallback PIN/RFID can be issued without retract.
AC3 — Given the issuance fails (vendor down), Then the request queues for retry and the front desk is notified.
Services. lock-integration-service, notification-service, reservation-service.
Frontend. Electron Desktop · Guest mobile.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract · Vendor-mock · Security.
Complexity. L.

US-MEL-0074 — Encode RFID card at front desk

As a Front-Desk staff member, I want to encode a physical RFID card at the desk, so that guests without smartphones can unlock.

AC1 — Given an encoder is connected, When I tap "Encode card", Then the card is encoded with the credential and the credential's physicalCardId is recorded.
AC2 — Given the encoder is not connected, Then the UI prompts to connect or fall back to mobile/PIN.
AC3 — Given I am offline, Then the encoding proceeds against cached vendor credentials and the issuance event is staged for sync.
Services. lock-integration-service.
Frontend. Electron Desktop · Encoder USB/serial.
DoD refs. Universal · API · Events · Security · Offline.
Test types. Unit · Integration · Offline · Vendor-mock.
Complexity. L.

US-MEL-0075 — PIN-based key for budget rooms

As a Tenant, I want PIN-based keys as a low-cost option, so that I can run rooms without RFID hardware.

AC1 — Given a room is configured for PIN, When I check in a guest, Then a PIN is generated, displayed once, and sent via SMS/WhatsApp.
AC2 — Given the PIN is regenerated, Then the prior PIN is invalidated and the new one issued.
AC3 — Given the PIN is shared by the guest's group, Then it works for all of them until reservation end.
Services. lock-integration-service, notification-service.
Frontend. Electron Desktop · Guest mobile.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0076 — Update key on date or room change

As a Front-Desk staff member, I want the key to update when a guest extends or changes rooms, so that access stays valid and scoped.

AC1 — Given dates extend, When I save, Then the credential's validUntil extends; mobile keys update without re-issue, RFID/PIN may require re-encode/regen.
AC2 — Given room changes, Then the old credential is revoked and the new one issued atomically.
AC3 — Given any update fails, Then the prior state is preserved and an alert fires.
Services. lock-integration-service, reservation-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract.
Complexity. L.

US-MEL-0077 — Revoke key on early checkout / cancel / lost-key

As a Front-Desk staff member, I want to revoke a key instantly, so that access is removed when a guest leaves or loses it.

AC1 — Given a guest checks out early, When I revoke, Then the credential transitions to revoked within 5 s p95 (online) or queues for sync (offline).
AC2 — Given a guest reports a lost key, Then I revoke and issue a fresh credential without changing reservation state.
AC3 — Given the vendor is unavailable, Then the revoke is queued, the guest is offered an interim solution, and the audit log records the delay.
Services. lock-integration-service, reservation-service, notification-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract · Vendor-mock.
Complexity. L.

US-MEL-0078 — Offline encoder fallback

As a Front-Desk staff member operating during an internet blackout, I want to encode RFID cards using cached vendor credentials, so that check-in continues uninterrupted.

AC1 — Given I am offline and the lock vendor supports offline encoder issuance, When I encode, Then the credential is created locally, the card encoded, and the issuance event is staged.
AC2 — Given sync resumes, Then the staged events flush in FIFO order and the central record is reconciled.
AC3 — Given the cached credentials are older than 24 h, Then the UI warns me and limits offline issuance count to a configurable threshold.
Services. lock-integration-service.
Frontend. Electron Desktop · Encoder USB/serial.
DoD refs. Universal · API · Events · Offline · Security.
Test types. Unit · Integration · Offline · Vendor-mock.
Complexity. XL.

US-MEL-0079 — Lock event anomaly detection

As a General Manager, I want anomalies in lock events (door opened repeatedly outside expected times, key used after revoke) flagged automatically, so that I can investigate.

AC1 — Given the lock vendor provides event streams, When the AI anomaly classifier scores an event highly, Then an alert appears in the GM inbox with AIProvenance.
AC2 — Given I dismiss as false-positive, Then the model is recorded for later retraining.
AC3 — Given the anomaly is real, Then I can take action (revoke, contact guest) directly from the alert.
Services. lock-integration-service, ai-orchestrator-service, notification-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · AI · Security.
Test types. Unit · Integration · AI eval · Security.
Complexity. L.

US-MEL-0080 — Vendor adapter abstraction (TTLock, Salto, Assa Abloy, Wiegand)

As a Platform engineer, I want all vendor SDKs behind one LockPort interface, so that new vendors plug in without reservation changes.

AC1 — Given I add a vendor adapter, Then it implements issue/update/revoke/getState and passes the contract test suite.
AC2 — Given I switch a tenant from TTLock to Salto, Then existing reservations re-issue keys via the new vendor on next check-in.
AC3 — Given an adapter throws an unsupported-feature error, Then the orchestrator falls back to a supported credential type.
Services. lock-integration-service.
Frontend. N/A.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract · Vendor-mock.
Complexity. XL.

US-MEL-0081 — Lock vendor secret rotation

As a Compliance Officer, I want vendor API secrets rotated on schedule, so that stolen secrets have a short lifespan.

AC1 — Given rotation is configured per vendor, Then Secret Manager rotates and the service hot-reloads.
AC2 — Given rotation fails, Then the previous secret remains valid until next attempt and an alert fires.
AC3 — Given rotation succeeds, Then an audit entry records {vendor, rotatedAt} without any secret values.
Services. lock-integration-service.
Frontend. N/A.
DoD refs. Universal · Security · Compliance · Observability.
Test types. Unit · Integration · Security.
Complexity. M.

12. EP-MEL-10 — Offline-First Desktop with Sync Engine

Outcome. The Electron desktop is fully usable offline with deterministic sync, per-aggregate conflict policies (never last-write-wins for monetary or inventory state), encrypted SQLite, AI worker (ONNX), and bandwidth-aware sync.

Primary owner. bff-backoffice-service (sync endpoints), every domain service via sync API, ai-orchestrator-service (edge models).

Journeys realised. J-05/06/07/12/19/20 (operate offline + sync recovery).

Cross-cutting AC for this epic. SQLCipher at rest; outbox FIFO with idempotency; trace propagation across the sync boundary; chaos tests for partial sync.

US-MEL-0082 — Local SQLite store with SQLCipher encryption

As a Platform engineer, I want the local SQLite encrypted with a derived per-device key, so that a stolen laptop doesn't leak tenant data.

AC1 — Given the desktop installs, Then SQLite is initialised with SQLCipher and the key is derived from a fragment in OS keychain + a fragment from the JWT-bound device identity.
AC2 — Given the user uninstalls or signs out, Then the database file is deleted.
AC3 — Given an attacker tries to open the file with sqlite3, Then the file is unreadable.
Services. Desktop only.
Frontend. Electron Desktop.
DoD refs. Universal · Security · Frontend.
Test types. Unit · Integration · Security.
Complexity. L.

US-MEL-0083 — Sync pull with cursor + delta

As a Desktop sync worker, I want to pull deltas since my last cursor, so that I'm efficient on low bandwidth.

AC1 — Given I call /sync/v1/pull with cursor, Then the server returns aggregates changed since cursor and a new cursor.
AC2 — Given the dataset is large, Then results are paginated; the worker processes pages and resumes on failure.
AC3 — Given the worker hasn't pulled in 24 h, Then a forced full re-sync is triggered.
Services. bff-backoffice-service, every domain service exposing sync.
Frontend. Electron Desktop sync worker.
DoD refs. Universal · API · Frontend · Observability.
Test types. Unit · Integration · Contract · Perf.
Complexity. L.

US-MEL-0084 — Sync push with idempotency

As a Desktop sync worker, I want to push outbox mutations with idempotency keys, so that retries never duplicate.

AC1 — Given I have queued mutations, When I push, Then the server applies them in order or returns conflicts.
AC2 — Given the same mutation is pushed twice, Then only one applies (idempotency-key check on the server inbox).
AC3 — Given a mutation fails validation, Then the worker surfaces the failure to the operator with an actionable error.
Services. bff-backoffice-service, every domain service.
Frontend. Electron Desktop sync worker.
DoD refs. Universal · API · Events · Frontend.
Test types. Unit · Integration · Contract · Chaos.
Complexity. L.

US-MEL-0085 — Per-aggregate conflict resolution policy

As a Platform engineer, I want per-aggregate conflict policies (e.g., monetary-state never LWW; inventory takes server authoritative; housekeeping LWW for assignment), so that correctness is preserved.

AC1 — Given a conflict exists, When the server merges, Then the policy from services/<svc>/SYNC_CONTRACT.md is applied deterministically.
AC2 — Given the policy requires operator decision, Then the conflict is surfaced in the desktop UI with side-by-side diffs.
AC3 — Given the operator decides, Then the decision is recorded with {conflictId, decisionBy, timestamp}.
Services. Every domain service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Frontend · Compliance.
Test types. Unit · Integration · Sync (per-aggregate matrix).
Complexity. XL.

US-MEL-0086 — Outbox flusher with FIFO ordering and backoff

As a Desktop sync worker, I want to flush the outbox in FIFO order with exponential backoff on failure, so that order-dependent operations stay correct.

AC1 — Given the outbox has 100 mutations, When I flush, Then they apply in insertion order or block on the failing item.
AC2 — Given an item fails, Then retry backoff is exponential up to 60s, then a poison-message queue.
AC3 — Given sync recovers after a long offline window, Then the worker resumes from the first pending item without skipping.
Services. Desktop · bff-backoffice-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events · Frontend.
Test types. Unit · Integration · Chaos · Offline.
Complexity. L.

US-MEL-0087 — Sync status pill always visible

As a Desktop user, I want a pill in the chrome that shows my sync state (online/offline/syncing/conflicts), so that I'm never surprised.

AC1 — Given I open the app, Then the pill renders within 100 ms with the current state.
AC2 — Given I tap the pill, Then I see the queue depth, last sync timestamp, and any pending conflicts.
AC3 — Given there are pending conflicts, Then the pill turns amber and a counter is shown.
Services. Desktop only.
Frontend. Electron Desktop.
DoD refs. Universal · Frontend · A11y.
Test types. Unit · A11y · Visual.
Complexity. S.

US-MEL-0088 — Edge AI inference via ONNX Runtime Node

As a Desktop AI worker, I want to run select models locally via ONNX, so that AI-assisted features work offline.

AC1 — Given the model bundle is signed and loaded, When I run inference, Then the result is returned with aiProvenance.local=true.
AC2 — Given a model fails to load, Then the feature gracefully degrades (no UI affordance) without crashing.
AC3 — Given the model is updated, Then the auto-updater fetches and verifies the new bundle on next start.
Services. ai-orchestrator-service (model registry).
Frontend. Electron Desktop AI worker.
DoD refs. Universal · AI · Frontend · Security.
Test types. Unit · Integration · AI eval · Security.
Complexity. L.

US-MEL-0089 — Bandwidth-aware sync throttle

As a Desktop sync worker, I want to detect link bandwidth and throttle accordingly, so that I don't saturate a slow connection.

AC1 — Given I detect ≤ 256 kbps, When syncing, Then I batch large objects and avoid large media transfers until on a faster link.
AC2 — Given the user explicitly forces sync, Then the throttle is bypassed.
AC3 — Given repeated timeouts, Then the worker pauses, schedules retry, and surfaces a status.
Services. Desktop only.
Frontend. Electron Desktop.
DoD refs. Universal · Frontend · Observability.
Test types. Unit · Integration · Chaos (bandwidth toxiproxy).
Complexity. M.

US-MEL-0090 — Migration runner for SQLite schema

As a Platform engineer, I want the desktop to apply schema migrations on startup safely, so that local schema stays in lockstep with the server.

AC1 — Given a migration exists, When the app starts, Then the migration runs in a transaction; on failure, the app rolls back and refuses to start until resolved.
AC2 — Given a migration is incompatible with stored data, Then the app proposes a re-sync and clears the offending tables.
AC3 — Given migrations succeed, Then the schema version is recorded.
Services. Desktop only.
Frontend. Electron Desktop.
DoD refs. Universal · Data · Frontend.
Test types. Unit · Integration · Migration.
Complexity. M.

13. EP-MEL-11 — AI-Assisted Operations (Dynamic Pricing, Forecasting, Anomalies, Drafts)

Outcome. AI capabilities are surfaced via a single orchestrator with provenance, HITL gates, budgets, and Vertex AI primary + ONNX edge fallback. AI suggests; humans decide on irreversible actions.

Primary owner. ai-orchestrator-service, with pricing-service, reservation-service, housekeeping-service, maintenance-service, notification-service, billing-service participating.

Journeys realised. J-15 (Configure Dynamic Pricing AI Suggestions), AI-thread inserts in J-05/06/07/19.

Cross-cutting AC for this epic. Every AI call goes through ai-orchestrator-service; HITL on irreversible actions; AI cost and budget enforcement; pre/post moderation.

US-MEL-0091 — Dynamic pricing suggestions (HITL)

As a General Manager, I want AI to suggest rate adjustments, so that I capture demand without manual analysis.

AC1 — Given AI suggests a rate change, When rendered in my inbox, Then I see baseline, suggested, expected uplift, and the rationale with AIProvenance.
AC2 — Given I accept, Then pricing-service updates the rate plan and a pricing.changed.v1 event fires with decisionId.
AC3 — Given I reject, Then the suggestion is closed, my decision is recorded, and the model is noted for retraining.
Services. ai-orchestrator-service, pricing-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · AI · Events.
Test types. Unit · Integration · AI eval · E2E.
Complexity. L.

US-MEL-0092 — Demand forecasting

As a General Manager, I want a 14- and 90-day occupancy forecast per property, so that I plan staffing and rates.

AC1 — Given I open the forecast view, Then the latest forecast renders within 800 ms and shows confidence bands.
AC2 — Given I drill into a date, Then I see contributing signals (historical, channel mix, events nearby).
AC3 — Given a market event is added (e.g., conference), Then I can re-run the forecast and see the lift.
Services. ai-orchestrator-service, analytics-service, pricing-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · AI · Frontend.
Test types. Unit · Integration · AI eval.
Complexity. L.

US-MEL-0093 — Anomaly detection (bookings, payments, locks)

As a General Manager, I want anomalies highlighted across bookings, payments, and lock events, so that I see issues before they become incidents.

AC1 — Given the daily anomaly job runs, Then flagged items appear in my inbox with severity, signals, and recommended action.
AC2 — Given I act on an anomaly (review, dismiss, escalate), Then the action is recorded and the model is updated.
AC3 — Given an anomaly is critical (suspected fraud), Then an immediate alert is fired to security@tenant.
Services. ai-orchestrator-service, reservation-service, payment-gateway-service, lock-integration-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · AI · Events · Security.
Test types. Unit · Integration · AI eval · Security.
Complexity. L.

US-MEL-0094 — AI-drafted multi-language guest messages

As a Front-Desk staff member, I want AI to draft guest messages in the right language with the right tone, so that I save time and avoid awkward translations.

AC1 — Given I pick a context (pre-arrival, late-checkout request, apology), Then AI returns a draft in the guest's locale with AIProvenance.
AC2 — Given I edit and send, Then the final text is logged and sent via notification-service.
AC3 — Given moderation flags content, Then the draft is blocked and I see the reason.
Services. ai-orchestrator-service, notification-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · AI · Events.
Test types. Unit · Integration · AI eval (moderation, hallucination).
Complexity. M.

US-MEL-0095 — Upsell recommendation surfacing

As a Tenant, I want AI to suggest upsells per reservation contextually, so that revenue per stay grows.

AC1 — Given a reservation exists, When AI scores upsell candidates, Then the front desk sees them at check-in with rationale.
AC2 — Given I accept on the guest's behalf, Then the upsell adds to folio and I record the decision.
AC3 — Given the upsell is sent to the guest as an offer, Then the offer carries AIProvenance and an opt-out.
Services. ai-orchestrator-service, reservation-service.
Frontend. Electron Desktop · Tenant Booking Mobile.
DoD refs. Universal · API · AI · Events.
Test types. Unit · Integration · AI eval · E2E.
Complexity. M.

US-MEL-0096 — AI cost guardrails per tenant

As a Platform engineer, I want per-tenant AI budgets enforced, so that runaway costs are impossible.

AC1 — Given a tenant has a daily budget, When approaching 80%, Then an alert fires and discretionary AI is degraded to lower-cost models.
AC2 — Given the budget is exceeded, Then non-essential AI suggestions are paused; HITL-required calls still run with manager approval.
AC3 — Given the budget resets, Then AI service resumes normally.
Services. ai-orchestrator-service.
Frontend. Control Plane · Electron Desktop banner.
DoD refs. Universal · API · AI · Observability.
Test types. Unit · Integration · Chaos.
Complexity. M.

US-MEL-0097 — HITL gate enforcement

As a Compliance Officer, I want HITL gates enforced for irreversible AI actions, so that AI cannot mutate guest-facing state without human review.

AC1 — Given an irreversible action is proposed by AI, When the orchestrator returns, Then a decisionId is required before the originating service commits.
AC2 — Given a service commits without decisionId, Then the call fails with MELMASTOON.AI.HITL_BYPASS and an audit alert fires.
AC3 — Given the human reviews and decides, Then the decision is captured and the action proceeds (or is blocked).
Services. ai-orchestrator-service, every consumer service.
Frontend. Electron Desktop.
DoD refs. Universal · API · AI · Security · Compliance.
Test types. Unit · Integration · Security.
Complexity. L.

US-MEL-0098 — Edge-vs-cloud equivalence for offered-both-ways capabilities

As a Platform engineer, I want edge ONNX models to be tested for equivalence against the cloud Vertex models, so that offline behaviour is predictable.

AC1 — Given a capability is offered both ways (e.g., housekeeping order suggestion), When the eval suite runs, Then equivalence within the configured tolerance is asserted.
AC2 — Given equivalence drifts beyond tolerance, Then a warning is fired and the edge model is flagged for retraining.
AC3 — Given a capability is cloud-only, Then the desktop UI hides the affordance offline (no fabrication).
Services. ai-orchestrator-service.
Frontend. N/A.
DoD refs. Universal · AI · Observability.
Test types. AI eval (equivalence).
Complexity. L.

14. EP-MEL-12 — Multi-Tenant Theming & Per-Tenant Booking Flow Config

Outcome. Runtime theme bootstrap for tenant booking surfaces; content blocks and layout presets editable in a controlled UI; preview, publish, rollback per version with audit.

Primary owner. theme-config-service, with file-storage-service, bff-consumer-service, bff-tenant-booking-service, notification-service participating.

US-MEL-0099 — Token-based theme bootstrap

As a Tenant booking site, I want to load the tenant's tokens at runtime, so that the same code base renders any tenant's brand.

AC1 — Given a request hits the tenant subdomain, When the BFF resolves theme, Then tokens (colours, typography, spacing) are returned within 100 ms p95.
AC2 — Given the theme is uncached, Then it is fetched from theme-config-service and cached for 5 minutes.
AC3 — Given a tenant publishes a new version, Then the cache invalidates within 60 s.
Services. theme-config-service, bff-tenant-booking-service, bff-consumer-service.
Frontend. Tenant Booking Web/Mobile.
DoD refs. Universal · API · Frontend.
Test types. Unit · Integration · Contract · Perf.
Complexity. M.

US-MEL-0100 — Layout presets

As an Owner, I want to choose from pre-built layout presets, so that I get a polished site without designing from scratch.

AC1 — Given preset options, When I pick one, Then the preview reflects it within 1 s.
AC2 — Given I save, Then the draft theme version increments.
AC3 — Given a preset has accessibility issues, Then it is rejected by validation.
Services. theme-config-service.
Frontend. Owner Portal.
DoD refs. Universal · API · Frontend · A11y.
Test types. Unit · A11y · Visual.
Complexity. M.

US-MEL-0101 — Content block editor with i18n

As an Owner, I want to edit content blocks (about, policies, FAQs) in multiple locales, so that the site speaks to all my markets.

AC1 — Given I choose a block and a locale, Then I edit and save with translation linking.
AC2 — Given I copy from one locale to another, Then the source text appears as the starting point.
AC3 — Given I save HTML in a block, Then it is sanitised against the allowlist.
Services. theme-config-service.
Frontend. Owner Portal.
DoD refs. Universal · API · Frontend · i18n.
Test types. Unit · Integration · A11y.
Complexity. M.

US-MEL-0102 — Preview vs Publish vs Rollback

As an Owner, I want to preview, publish, and roll back theme versions, so that I have safety in change management.

AC1 — Given I have a draft, When I preview, Then a signed preview URL renders the draft for 24 h.
AC2 — Given I publish, Then the draft becomes live within 60 s.
AC3 — Given I roll back to v(N-1), Then v(N-1) is live within 60 s and an event records the rollback.
Services. theme-config-service, bff-tenant-booking-service, bff-consumer-service.
Frontend. Owner Portal.
DoD refs. Universal · API · Events · Observability.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0103 — Marketing review workflow

As a Marketing Reviewer, I want a queue of pending themes with diff view, so that I review fast.

AC1 — Given I open the queue, Then I see themes pending review with submitter and submission time.
AC2 — Given I open a theme, Then I see a side-by-side diff vs the current live version.
AC3 — Given I approve or reject with comments, Then the submitter is notified and the state transitions.
Services. theme-config-service, notification-service, iam-service.
Frontend. Control Plane.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0104 — Per-tenant booking flow rule configuration

As an Owner, I want to configure booking-flow rules (steps, fields, optional add-ons) per tenant, so that the flow matches my operation.

AC1 — Given I disable "special requests", When the booking flow renders, Then the field is hidden.
AC2 — Given I add a custom mandatory field (e.g., national ID), Then the field appears and is required.
AC3 — Given the configuration violates a hard invariant (e.g., remove guest name), Then the configuration is rejected.
Services. theme-config-service, bff-tenant-booking-service.
Frontend. Owner Portal · Tenant Booking Web/Mobile.
DoD refs. Universal · API · Frontend.
Test types. Unit · Integration · E2E.
Complexity. M.

15. EP-MEL-13 — Reporting (Operational, Financial, Regulatory)

Outcome. Pre-built report templates (occupancy, ADR, RevPAR, GPAR, EOD, payment mix, channel mix, daily guest registration where mandated) with scheduled runs, multi-format exports (PDF/CSV/Excel), offline cache for recent reports.

Primary owner. reporting-service, with analytics-service, reservation-service, billing-service, payment-gateway-service, file-storage-service, notification-service participating.

US-MEL-0105 — Operational report templates (occupancy, ADR, RevPAR)

As a General Manager, I want standard operational reports, so that I track core KPIs without building dashboards.

AC1 — Given I open "Occupancy", Then the report renders for the chosen date range with breakdowns by room type and channel.
AC2 — Given I export to CSV, Then the file is generated and downloaded within 5 s for ranges ≤ 90 days.
AC3 — Given I am offline, Then the most recently viewed reports are available from cache.
Services. reporting-service, analytics-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Frontend · Offline.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0106 — Financial reports (folio, revenue, payment mix, taxes)

As a Finance/Admin, I want financial reports with FX-snapshot detail, so that I can reconcile and report taxes.

AC1 — Given I open "Revenue by date", Then the report shows charges in chargeCurrency and settlementCurrency.
AC2 — Given I open "Tax summary", Then taxes are broken down by jurisdiction and rate.
AC3 — Given I export to Excel, Then the file conforms to the configured tenant template.
Services. reporting-service, billing-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Compliance.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0107 — Daily guest registration export (regulatory, where mandated)

As a Receptionist/Admin, I want to export the daily guest registration in the official format (e.g., for local police/tourism authority), so that we comply with the mandate.

AC1 — Given the tenant operates in a jurisdiction requiring DGR, When I trigger the export, Then the file is generated in the official format and signed with tenant credentials.
AC2 — Given the export is generated, Then an audit entry records the time and operator.
AC3 — Given I schedule it daily at 23:30, Then it runs automatically and the result is emailed to the configured address.
Services. reporting-service, reservation-service, notification-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Compliance · Security.
Test types. Unit · Integration · E2E.
Complexity. L.

US-MEL-0108 — Scheduled runs and email delivery

As a General Manager, I want to schedule reports for daily/weekly delivery, so that I get them in my inbox.

AC1 — Given I configure a schedule, When the time arrives, Then the report is generated and emailed.
AC2 — Given generation fails, Then I am notified and the schedule retries with backoff.
AC3 — Given I disable the schedule, Then future runs do not occur.
Services. reporting-service, notification-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0109 — Multi-format export (PDF/CSV/Excel)

As a GM/Finance, I want to choose the export format per report, so that the receiving system can consume it.

AC1 — Given I pick PDF, Then the report renders with the tenant header/footer and locale.
AC2 — Given I pick CSV, Then the file uses UTF-8 + BOM for spreadsheet compatibility.
AC3 — Given I pick Excel, Then the file uses xlsx with one sheet per logical section.
Services. reporting-service, file-storage-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Frontend · i18n.
Test types. Unit · Integration.
Complexity. M.

US-MEL-0110 — Offline-cached recent reports

As a GM, I want recent reports cached locally, so that I can review them without connectivity.

AC1 — Given I view a report online, Then it is cached locally (encrypted SQLite blob + signed PDF).
AC2 — Given I am offline, Then I can re-open cached reports up to 30 days old.
AC3 — Given the cache exceeds 200 MB, Then the LRU eviction trims it.
Services. reporting-service, Desktop.
Frontend. Electron Desktop.
DoD refs. Universal · Frontend · Offline · Security.
Test types. Unit · Integration · Offline.
Complexity. M.

16. EP-MEL-14 — Analytics Pipeline (Events → BigQuery → Dashboards → AI Signals)

Outcome. All Pub/Sub events ingested into BigQuery via streaming inserts, ETL transforms produce conformed marts, a query API exposes metrics to dashboards, and the AI service consumes the signals.

Primary owner. analytics-service, with all event publishers, ai-orchestrator-service.

US-MEL-0111 — Event ingestion to BigQuery

As a Platform engineer, I want every domain event ingested into BigQuery, so that analytics is event-sourced.

AC1 — Given an event is published, Then it lands in the corresponding BQ raw table within 2 minutes p95.
AC2 — Given the schema evolves, Then the BQ table evolves backward-compatibly (additive only).
AC3 — Given ingestion fails, Then the message goes to a DLQ and an alert fires.
Services. analytics-service, all event publishers.
Frontend. N/A.
DoD refs. Universal · API · Events · Observability.
Test types. Unit · Integration · Contract.
Complexity. L.

US-MEL-0112 — Conformed marts (occupancy, revenue, channel)

As a Data engineer, I want conformed marts via scheduled ETL, so that dashboards query stable data.

AC1 — Given marts are scheduled, When they run, Then the lineage is captured.
AC2 — Given a source schema changes, Then the ETL adapts or fails-loudly with a runbook link.
AC3 — Given the marts succeed, Then dashboards refresh.
Services. analytics-service.
Frontend. N/A.
DoD refs. Universal · Data · Observability.
Test types. Unit · Integration · DataQuality.
Complexity. L.

US-MEL-0113 — Query API for dashboards

As a Frontend engineer, I want a typed query API for KPI metrics, so that dashboards aren't writing SQL.

AC1 — Given I request revenue?range=30d, Then the API returns the metric within 500 ms p95.
AC2 — Given I request a metric I don't have permission for, Then I get 403.
AC3 — Given I request an undefined metric, Then I get 404.
Services. analytics-service.
Frontend. Electron Desktop dashboards.
DoD refs. Universal · API · Security.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0114 — Cohort & funnel definitions

As a Analyst, I want to define cohorts (e.g., booking source) and funnels (e.g., search → confirm), so that I analyse behaviour.

AC1 — Given I define a cohort, Then it persists and can be reused.
AC2 — Given I define a funnel, Then I see step-by-step drop-off rates.
AC3 — Given a definition is shared, Then other tenant analysts can use it within their tenant only.
Services. analytics-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Frontend.
Test types. Unit · Integration · E2E.
Complexity. M.

US-MEL-0115 — AI input signals from analytics

As a Platform engineer, I want key analytics signals exposed to ai-orchestrator-service, so that AI features have grounding data.

AC1 — Given a forecast model needs occupancy history, When it runs, Then it pulls from the conformed marts.
AC2 — Given a signal is missing, Then the model degrades gracefully with aiProvenance carrying dataMissing=true.
AC3 — Given signal access is audited, Then the access log records {model, signal, timestamp, tenantId}.
Services. analytics-service, ai-orchestrator-service.
Frontend. N/A.
DoD refs. Universal · API · AI · Observability.
Test types. Unit · Integration.
Complexity. M.

17. EP-MEL-15 — Multi-Channel Notification (Email, SMS, WhatsApp, Push)

Outcome. Multi-language templates with RTL/LTR variants, scheduling, AI-drafted suggestions, delivery audit, and provider abstraction across email/SMS/WhatsApp/push.

Primary owner. notification-service, with ai-orchestrator-service, file-storage-service, all BFFs participating.

US-MEL-0116 — Templates with i18n + RTL/LTR variants

As a Tenant, I want notification templates per locale with RTL/LTR baked in, so that all guests get correctly-formed messages.

AC1 — Given I author a template in 3 locales, Then the system stores all versions and the template carries dir per locale.
AC2 — Given a guest is ar-EG, Then the Arabic version sends with dir=rtl rendering.
AC3 — Given a locale is missing, Then the system falls back to the tenant's default locale and records the gap.
Services. notification-service, theme-config-service.
Frontend. Owner Portal.
DoD refs. Universal · API · Frontend · i18n.
Test types. Unit · Integration · i18n.
Complexity. M.

US-MEL-0117 — Scheduled notifications (pre-arrival, post-stay)

As a Tenant, I want to schedule pre-arrival and post-stay messages, so that I engage guests at the right time.

AC1 — Given I configure a sequence, Then messages are queued at the right time relative to reservation events.
AC2 — Given the guest opts out, Then further sequence messages stop.
AC3 — Given sending fails, Then retry with exponential backoff until TTL.
Services. notification-service.
Frontend. Owner Portal · Electron Desktop.
DoD refs. Universal · API · Events.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0118 — AI-drafted message suggestions

As a Front-Desk staff member, I want AI to draft messages I can edit and send, so that I save time.

AC1 — Given a context, When I tap "Draft", Then AI returns a draft with AIProvenance.
AC2 — Given I send, Then the final text is recorded and delivered via the chosen channel.
AC3 — Given moderation flags, Then the draft is blocked.
Services. ai-orchestrator-service, notification-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · AI.
Test types. Unit · Integration · AI eval.
Complexity. M.

US-MEL-0119 — Delivery audit & retry

As a Compliance Officer, I want every notification delivery attempt logged with status, so that I can audit communication.

AC1 — Given a message is sent, Then the audit log records {messageId, channel, attempts, finalStatus}.
AC2 — Given delivery fails, Then retry with backoff up to 24 h.
AC3 — Given the recipient marks spam (where measurable), Then the future deliveries to that recipient are paused.
Services. notification-service.
Frontend. Electron Desktop · Control Plane.
DoD refs. Universal · API · Compliance · Observability.
Test types. Unit · Integration · Contract.
Complexity. M.

US-MEL-0120 — Channel abstraction (email/SMS/WhatsApp/push)

As a Platform engineer, I want a single port for all channels with vendor adapters, so that new providers add cleanly.

AC1 — Given I add a new provider, Then it implements the channel port and passes contract tests.
AC2 — Given a provider is throttled, Then the orchestrator routes to a healthy alternate where configured.
AC3 — Given all providers for a channel are down, Then the message queues with a clear error.
Services. notification-service.
Frontend. N/A.
DoD refs. Universal · API · Events · Security.
Test types. Unit · Integration · Contract.
Complexity. L.

US-MEL-0121 — Recipient preference management

As a Guest, I want to manage which channels I get messages on, so that I'm not over-messaged.

AC1 — Given I open my preference link, Then I can opt in/out per channel.
AC2 — Given I opt out of all transactional, Then only legally required messages send.
AC3 — Given my preferences change, Then future sends respect the new state within 60 s.
Services. notification-service.
Frontend. Tenant Booking Web/Mobile.
DoD refs. Universal · API · Compliance.
Test types. Unit · Integration.
Complexity. S.

18. EP-MEL-16 — File Storage with Signed URLs, Virus Scan, Image Optimization

Outcome. A single API for all media; tenant-prefix isolation; lifecycle policies; CDN; virus scanning; image optimization for booking-site assets.

Primary owner. file-storage-service, with every consumer service participating.

US-MEL-0122 — Upload with signed URL & virus scan

As a Tenant or Guest, I want to upload files via signed URL with virus scanning, so that infected files don't reach the platform.

AC1 — Given I request an upload URL, Then a signed PUT URL is returned with TTL and content-type constraints.
AC2 — Given I upload a file, Then it is scanned and only marked available if clean.
AC3 — Given a file is infected, Then it is quarantined and the requester notified.
Services. file-storage-service.
Frontend. Owner Portal · Electron Desktop · Tenant Booking Web/Mobile.
DoD refs. Universal · API · Security.
Test types. Unit · Integration · Security.
Complexity. M.

US-MEL-0123 — Tenant prefix isolation

As a Compliance Officer, I want every object scoped to a tenant prefix in storage, so that cross-tenant exfiltration is impossible.

AC1 — Given any upload, Then the storage path is {tenantId}/{type}/{id}.
AC2 — Given any read, Then it must include tenantId and is rejected if mismatched.
AC3 — Given an admin attempts cross-tenant access, Then the request requires platform-admin claim and is audited.
Services. file-storage-service.
Frontend. N/A.
DoD refs. Universal · Security · Compliance.
Test types. Unit · Integration · Security.
Complexity. M.

US-MEL-0124 — Image optimization & CDN

As a Tenant, I want images served from a CDN in optimised formats, so that my booking site is fast everywhere.

AC1 — Given I upload an image, Then WebP/AVIF variants are generated automatically at 320/768/1024/1440 widths.
AC2 — Given the page requests an image, Then the CDN serves the optimal format/size for the device.
AC3 — Given the original is updated, Then variants are regenerated and the CDN cache is invalidated.
Services. file-storage-service.
Frontend. Tenant Booking Web/Mobile · Consumer Web/Mobile.
DoD refs. Universal · API · Frontend · Perf.
Test types. Unit · Integration · Perf.
Complexity. M.

US-MEL-0125 — Lifecycle policies (retention, archival)

As a Compliance Officer, I want lifecycle rules per file type, so that old data is moved or deleted on schedule.

AC1 — Given invoices retention is 7 years, Then invoices auto-move to cold storage at 90 days and are deleted at 7 years.
AC2 — Given ID scans retention is 30 days, Then ID scans auto-delete after 30 days.
AC3 — Given a tenant requests early deletion, Then the deletion is processed with audit.
Services. file-storage-service.
Frontend. N/A.
DoD refs. Universal · Compliance · Security.
Test types. Unit · Integration.
Complexity. M.

19. EP-MEL-17 — Identity, Auth, Multi-Tenant RBAC, MFA, SSO, Device Binding

Outcome. Full IAM including JWT lifecycle, RBAC/ABAC with tenant scope, MFA, OIDC/SAML SSO for chain operators, and Electron device binding for offline sessions.

Primary owner. iam-service, with tenant-service, staff-service, bff-backoffice-service, notification-service participating.

US-MEL-0126 — JWT issuance & rotation

As a Platform engineer, I want standard JWT issuance with refresh rotation, so that sessions are secure and short-lived.

AC1 — Given I sign in, Then an access JWT (≤ 15 min) and a refresh token (≤ 30 days) are issued.
AC2 — Given I refresh, Then the refresh token rotates and the previous family is revoked on detected reuse.
AC3 — Given I sign out, Then all tokens are revoked.
Services. iam-service.
Frontend. All.
DoD refs. Universal · API · Security.
Test types. Unit · Integration · Security.
Complexity. L.

US-MEL-0127 — RBAC with tenant scope

As a Platform engineer, I want RBAC with explicit tenant scope, so that roles can't accidentally span tenants.

AC1 — Given a role grant, Then it carries (tenantId, role) and the JWT tids claim lists allowed tenants.
AC2 — Given a request with X-Tenant-Id not in JWT tids, Then 403 returns.
AC3 — Given roles change, Then the user's next token carries the change and prior tokens may be revoked per policy.
Services. iam-service, tenant-service.
Frontend. N/A.
DoD refs. Universal · API · Security · Compliance.
Test types. Unit · Integration · Security.
Complexity. L.

US-MEL-0128 — MFA with TOTP and WebAuthn passkeys

As an Owner/GM, I want MFA enforced for privileged roles, so that account takeover risk is reduced.

AC1 — Given I enrol TOTP, When I sign in, Then I am prompted for a TOTP code.
AC2 — Given I enrol a passkey, Then I can sign in passwordless.
AC3 — Given the tenant requires passkeys for admins, Then admins must enrol before reaching admin surfaces.
Services. iam-service.
Frontend. Owner Portal · Electron Desktop.
DoD refs. Universal · API · Security · A11y.
Test types. Unit · Integration · Security · A11y.
Complexity. L.

US-MEL-0129 — OIDC/SAML SSO for chain operators

As a Chain Operator, I want to sign in via my corporate IdP, so that I don't manage another password.

AC1 — Given my org has SSO configured, When I sign in via IdP, Then a JWT is issued with my tenant claims.
AC2 — Given JIT provisioning is enabled, Then unknown users are auto-provisioned with default role.
AC3 — Given SAML signature is invalid, Then sign-in fails with 401 and an audit entry.
Services. iam-service, tenant-service, notification-service.
Frontend. Owner Portal · Electron Desktop.
DoD refs. Universal · API · Security.
Test types. Unit · Integration · Contract · Security.
Complexity. L.

US-MEL-0130 — Device binding for desktop offline sessions

As an Electron Desktop, I want to bind a device to a user for offline sessions, so that offline work is authenticated.

AC1 — Given I bind a device, Then an Ed25519 keypair is generated client-side and the public key is registered.
AC2 — Given I am offline, Then the device key signs sync requests on reconnect with proof-of-possession.
AC3 — Given an admin revokes a device, Then the device cannot sync after the next online check.
Services. iam-service, bff-backoffice-service.
Frontend. Electron Desktop.
DoD refs. Universal · API · Security · Frontend.
Test types. Unit · Integration · Security.
Complexity. L.

US-MEL-0131 — Password reset & recovery

As a User, I want to reset my password securely, so that I can recover from forgotten credentials.

AC1 — Given I request reset for any email, Then API returns 202 regardless of whether the email exists.
AC2 — Given my reset link is older than 1 h, Then it returns 410.
AC3 — Given I complete reset, Then all my sessions are optionally revoked.
Services. iam-service, notification-service.
Frontend. Owner Portal · Tenant Booking Web/Mobile.
DoD refs. Universal · API · Security · A11y.
Test types. Unit · Integration · Security.
Complexity. M.

US-MEL-0132 — Audit log of authn events

As a Compliance Officer, I want every authn event logged immutably, so that I can audit.

AC1 — Given any sign-in, sign-out, or token refresh, Then an audit entry is written with {userId, tenantId, ip, ua, decision}.
AC2 — Given a suspicious anomaly is detected (impossible travel, new device + sensitive action), Then an alert fires.
AC3 — Given I export the audit log, Then it is in a tamper-evident format.
Services. iam-service.
Frontend. Control Plane.
DoD refs. Universal · Compliance · Security · Observability.
Test types. Unit · Integration · Security.
Complexity. M.

20. EP-MEL-18 — Multi-Language & RTL/LTR

Outcome. Pashto, Dari, Persian, Arabic, English, French, Tajik supported across content + UI strings + native menus + bidi-safe layouts + locale-aware fonts.

Primary owner. theme-config-service, with notification-service and all frontends participating.

US-MEL-0133 — i18n bundle generation & loading

As a Frontend engineer, I want the i18n bundle generated at build, so that each locale loads efficiently.

AC1 — Given strings are extracted via ICU MessageFormat, Then locale bundles are emitted per locale.
AC2 — Given the user picks a locale, Then the relevant bundle loads on demand and caches.
AC3 — Given a string key is missing, Then a fallback locale is used and the gap logged.
Services. All frontends.
Frontend. All.
DoD refs. Universal · Frontend · i18n.
Test types. Unit · i18n.
Complexity. M.

US-MEL-0134 — RTL bidi-safe layouts

As a Designer/Engineer, I want all layouts to use logical CSS, so that RTL works without per-locale styles.

AC1 — Given any UI surface, Then logical CSS only is used (padding-inline, margin-block).
AC2 — Given RTL is active, Then the entire shell mirrors correctly.
AC3 — Given mixed-direction text appears (e.g., Pashto + English), Then bidi rendering is correct.
Services. All frontends.
Frontend. All.
DoD refs. Universal · Frontend · A11y · i18n.
Test types. Unit · Visual (RTL screenshots) · A11y.
Complexity. L.

US-MEL-0135 — Locale-aware date, number, currency

As a User, I want dates, numbers, and currencies to render in my locale style, so that the UI feels native.

AC1 — Given my locale is ps-AF, Then dates render in the configured presentational calendar (Hijri/Solar Hijri/Gregorian) per tenant default.
AC2 — Given I switch numerals to Arabic-Indic, Then all displayed numbers use Arabic-Indic except inputs that stay European for safety.
AC3 — Given my display currency is USD, Then prices show with the correct symbol and grouping.
Services. All frontends.
Frontend. All.
DoD refs. Universal · Frontend · i18n.
Test types. Unit · i18n.
Complexity. M.

US-MEL-0136 — Native OS menus per locale

As a Desktop user, I want the OS menu in my language, so that the app feels native.

AC1 — Given my user locale is ps-AF, Then the Electron native menu is in Pashto.
AC2 — Given I switch locale at runtime, Then menus update without app restart.
AC3 — Given OS is RTL-aware (Windows, macOS), Then the menu mirrors per OS conventions.
Services. Desktop only.
Frontend. Electron Desktop.
DoD refs. Universal · Frontend · i18n.
Test types. Unit · i18n · Visual.
Complexity. S.

US-MEL-0137 — Locale-aware fonts

As a Designer, I want font stacks per script, so that Pashto, Dari, Arabic render with the correct font.

AC1 — Given a script is detected, Then the appropriate font is loaded (Noto Sans Pashto/Arabic/etc.).
AC2 — Given the font fails to load, Then the system falls back gracefully.
AC3 — Given the font weight is requested, Then the right weight is used or fallback chosen.
Services. All frontends.
Frontend. All.
DoD refs. Universal · Frontend · i18n · Perf.
Test types. Unit · Visual · Perf.
Complexity. M.

US-MEL-0138 — Translation workflow for content

As a Tenant, I want to manage translations for content blocks across locales, so that my site speaks to all my markets.

AC1 — Given I edit one locale, Then I can mark others "needs review".
AC2 — Given I publish, Then missing translations fall back to default locale with a banner.
AC3 — Given I bulk import translations from CSV, Then the import validates keys and applies them.
Services. theme-config-service.
Frontend. Owner Portal.
DoD refs. Universal · API · Frontend · i18n.
Test types. Unit · Integration · i18n.
Complexity. M.

21. EP-MEL-19 — Compliance & Regulatory (Tax, KYC, Audit Logs)

Outcome. Per-jurisdiction tax engine, KYC for some markets, immutable audit log, daily registration where mandated, data residency posture.

Primary owner. pricing-service (tax), billing-service (folio), reporting-service (regulatory exports), analytics-service, iam-service (audit) participating.

US-MEL-0139 — Tax engine with jurisdiction rules

As a Tenant, I want taxes computed correctly per jurisdiction, so that I report accurately.

AC1 — Given the property's jurisdiction, When I quote a price, Then taxes are computed per the jurisdiction's rates and rules.
AC2 — Given a guest is tax-exempt (diplomatic), Then the exemption applies on proof.
AC3 — Given tax rates change, Then new bookings use the new rate; existing bookings use the snapshot at confirm.
Services. pricing-service, billing-service.
Frontend. Tenant Booking Web/Mobile · Electron Desktop.
DoD refs. Universal · API · Compliance.
Test types. Unit (jurisdiction matrix) · Integration · Contract.
Complexity. L.

US-MEL-0140 — KYC for tenants in regulated markets

As an Owner in a regulated market, I want to complete KYC during onboarding, so that I can transact.

AC1 — Given my country requires KYC, Then I am prompted to upload documents during onboarding.
AC2 — Given my documents pass review, Then my tenant transitions from pending_kyc to active.
AC3 — Given my documents fail, Then I am notified with reasons and can resubmit.
Services. tenant-service, file-storage-service, notification-service.
Frontend. Owner Portal · Control Plane (review).
DoD refs. Universal · API · Compliance · Security.
Test types. Unit · Integration · E2E.
Complexity. L.

US-MEL-0141 — Immutable audit log with daily Merkle anchoring

As a Compliance Officer, I want an immutable audit log with daily anchoring, so that tampering is detectable.

AC1 — Given an event of regulatory interest occurs, Then an audit entry is appended.
AC2 — Given the daily anchor job runs, Then a Merkle root is computed and stored.
AC3 — Given I verify a historical entry, Then I can prove inclusion via the Merkle path.
Services. Audit subscriber.
Frontend. Control Plane.
DoD refs. Universal · Compliance · Security.
Test types. Unit · Integration · Security.
Complexity. L.

US-MEL-0142 — Data residency enforcement

As a Compliance Officer, I want all writes pinned to the tenant's home region, so that residency is enforceable.

AC1 — Given a tenant home region is me-central1, Then all writes go to that region.
AC2 — Given a cross-region read is attempted, Then it is denied unless the request carries a platform-admin claim.
AC3 — Given residency posture is reported, Then the report shows per-tenant region.
Services. Every service.
Frontend. Control Plane.
DoD refs. Universal · Compliance · Security · Observability.
Test types. Unit · Integration · Security.
Complexity. L.

As a Guest, I want to request erasure of my personal data, so that my privacy is respected.

AC1 — Given I request erasure, Then the request is logged and a 30-day window starts.
AC2 — Given the window completes without retraction, Then PII fields on my reservations are tombstoned (not destroyed for legal/financial records, but unreadable).
AC3 — Given the erasure completes, Then I receive a certificate of completion.
Services. Every service touching PII.
Frontend. Tenant Booking Web/Mobile.
DoD refs. Universal · Compliance · Security.
Test types. Unit · Integration · E2E · Security.
Complexity. L.

22. EP-MEL-20 — Observability, Reliability, Cost Controls

Outcome. Logs, metrics, traces, SLOs, alerting, cost dashboards, autoscaling — cross-cutting across every service.

Primary owner. Platform/SRE; every service participates.

US-MEL-0144 — Structured logs with trace_id, tenant_id, request_id

As a SRE, I want every log line carrying {trace_id, tenant_id, request_id}, so that I can join logs to traces.

AC1 — Given any HTTP request, Then every log line emitted during that request includes those three fields.
AC2 — Given an event is consumed, Then the trace context is propagated and logs continue to carry it.
AC3 — Given I query by trace_id, Then all related logs return.
Services. Every service.
Frontend. N/A.
DoD refs. Universal · Observability.
Test types. Unit · Integration.
Complexity. M.

US-MEL-0145 — Metrics with tenant_id label

As a SRE, I want key metrics labeled by tenant_id, so that I can attribute load and errors to tenants.

AC1 — Given the metric is HTTP request rate, Then it carries tenant_id.
AC2 — Given the metric is event publish count, Then it carries tenant_id.
AC3 — Given the cardinality risks blowing up, Then the high-cardinality is bucketed via approved aggregations.
Services. Every service.
Frontend. N/A.
DoD refs. Universal · Observability.
Test types. Unit · Integration.
Complexity. M.

US-MEL-0146 — Distributed traces with W3C traceparent

As a SRE, I want traces propagated across HTTP, Pub/Sub, and the desktop sync boundary, so that I can debug end-to-end.

AC1 — Given an HTTP request enters, Then traceparent is propagated to downstream services and events.
AC2 — Given the desktop sync pushes, Then the trace continues into the cloud.
AC3 — Given I open the trace in Cloud Trace, Then I see the entire path.
Services. Every service.
Frontend. All (including Electron Desktop).
DoD refs. Universal · Observability.
Test types. Unit · Integration · E2E.
Complexity. L.

US-MEL-0147 — SLOs and alerting

As a SRE, I want SLOs per service with alerting on burn rate, so that I prioritise toil.

AC1 — Given a service has SLOs (latency, errors, sync lag), Then burn-rate alerts fire when budget is consumed too fast.
AC2 — Given an alert fires, Then a runbook URL is included.
AC3 — Given the SLO is consistently met, Then the budget is restored monthly.
Services. Every service.
Frontend. N/A.
DoD refs. Universal · Observability.
Test types. Unit (SLI computation).
Complexity. M.

US-MEL-0148 — Cost dashboards per tenant + per service

As a Platform engineer, I want cost dashboards per tenant and per service, so that I can spot expensive tenants and services.

AC1 — Given the dashboard renders, Then I see daily cost per tenant and per service.
AC2 — Given a tenant exceeds expected cost band, Then an alert fires.
AC3 — Given a service exceeds expected cost band, Then SRE investigates.
Services. Platform.
Frontend. Control Plane.
DoD refs. Universal · Observability.
Test types. Unit · Integration.
Complexity. M.

US-MEL-0149 — Autoscaling policies for Cloud Run

As a SRE, I want Cloud Run autoscaling tuned per service, so that cost and latency are balanced.

AC1 — Given a service receives bursts, When scaling, Then new instances start within tolerable cold-start.
AC2 — Given sustained high load, Then the service scales out to the configured ceiling.
AC3 — Given load drops, Then instances scale to zero or a warm minimum per service config.
Services. Every service.
Frontend. N/A.
DoD refs. Universal · Observability · Perf.
Test types. Perf · Chaos.
Complexity. M.

US-MEL-0150 — Synthetic monitoring of P0 journeys

As a SRE, I want synthetic probes for booking, sync, AI gateway, so that I detect outages before users do.

AC1 — Given the synthetic runs every 5 min, Then failures alert within 2 cycles.
AC2 — Given alerts route to on-call, Then the on-call has a runbook.
AC3 — Given the synthetic uses a sandbox tenant, Then real-tenant data is not affected.
Services. Platform.
Frontend. N/A.
DoD refs. Universal · Observability.
Test types. E2E (synthetic).
Complexity. M.

US-MEL-0151 — Error budget enforcement

As a Platform engineering manager, I want error budgets to guide release pace, so that stability is rewarded.

AC1 — Given a service exhausts its budget, Then new feature rollouts pause until restored.
AC2 — Given the budget is recovering, Then rollouts resume per policy.
AC3 — Given the team needs an exception, Then a documented decision is required.
Services. Platform.
Frontend. N/A.
DoD refs. Universal · Observability.
Test types. N/A (process).
Complexity. S.

US-MEL-0152 — Feature flags with tenant scope

As a Platform engineer, I want feature flags scoped per tenant, so that I can roll out cautiously.

AC1 — Given a flag is enabled for tenant T, Then only T sees the feature.
AC2 — Given a flag is disabled mid-flight, Then the surface degrades within 60 s globally.
AC3 — Given flag state changes are audited, Then the audit captures who/when/why.
Services. Platform.
Frontend. All.
DoD refs. Universal · API · Observability · Security.
Test types. Unit · Integration.
Complexity. M.

US-MEL-0153 — Canary rollouts with auto-rollback

As a SRE, I want canary rollouts with automatic rollback on SLO regression, so that bad releases revert fast.

AC1 — Given I deploy, Then 5% of traffic is canaried for 30 min.
AC2 — Given SLO regresses on canary, Then auto-rollback fires.
AC3 — Given the canary holds, Then traffic ramps to 100%.
Services. Platform.
Frontend. N/A.
DoD refs. Universal · Observability.
Test types. Chaos.
Complexity. M.

US-MEL-0154 — Backup & restore for Cloud SQL

As a SRE, I want automated backups with periodic restore drills, so that data loss risk is low.

AC1 — Given the daily backup schedule, Then PITR is enabled and validated.
AC2 — Given a quarterly drill, Then a restore to a staging instance succeeds within RTO.
AC3 — Given a real incident, Then the runbook is followed and RTO/RPO targets met.
Services. Platform.
Frontend. N/A.
DoD refs. Universal · Observability · Compliance.
Test types. Drill.
Complexity. M.

US-MEL-0155 — Pub/Sub DLQ handling

As a SRE, I want failed events routed to DLQs with replay tooling, so that poison messages don't block.

AC1 — Given a message fails > N times, Then it routes to the DLQ.
AC2 — Given DLQ depth grows beyond threshold, Then an alert fires.
AC3 — Given I replay from DLQ, Then the replay is bounded and audited.
Services. Platform.
Frontend. N/A.
DoD refs. Universal · Observability.
Test types. Chaos · Integration.
Complexity. M.

US-MEL-0156 — Runbook discoverability

As a SRE, I want every alert to link to a runbook, so that on-call resolves fast.

AC1 — Given an alert exists, Then it has a runbook URL.
AC2 — Given a runbook is stale (> 6 months without review), Then an issue is auto-created.
AC3 — Given the on-call resolves, Then the resolution feeds back into the runbook.
Services. Platform.
Frontend. N/A.
DoD refs. Universal · Observability.
Test types. N/A.
Complexity. S.

US-MEL-0157 — Incident timeline and post-mortems

As an Engineering Manager, I want incident timelines auto-generated from logs/events/traces, so that post-mortems are evidence-based.

AC1 — Given an incident is declared, Then the timeline is auto-collected.
AC2 — Given post-mortem is published, Then it includes blameless analysis and follow-up issues.
AC3 — Given follow-ups are open, Then they are tracked to closure.
Services. Platform.
Frontend. Control Plane.
DoD refs. Universal · Observability · Compliance.
Test types. N/A (process).
Complexity. M.

US-MEL-0158 — RUM (Real User Monitoring) for booking surfaces

As a Frontend engineer, I want RUM on the consumer + tenant booking surfaces, so that I see real LCP/INP/CLS.

AC1 — Given a user loads a page, Then RUM events are sampled and shipped.
AC2 — Given Web Vitals breach, Then alerts fire and an investigation is opened.
AC3 — Given a release degrades RUM, Then the canary is rolled back.
Services. Frontends.
Frontend. Consumer Web · Tenant Booking Web.
DoD refs. Universal · Frontend · Observability.
Test types. Unit · Perf.
Complexity. M.

US-MEL-0159 — Sync telemetry (queue depth, conflict rate)

As a SRE, I want sync telemetry visible per tenant, so that I can spot offline-pain tenants.

AC1 — Given the desktop syncs, Then queue depth and conflict count are reported.
AC2 — Given the conflict rate exceeds threshold, Then the team investigates.
AC3 — Given the queue depth grows, Then an alert fires.
Services. bff-backoffice-service.
Frontend. Electron Desktop.
DoD refs. Universal · Observability.
Test types. Unit · Integration.
Complexity. M.

US-MEL-0160 — AI cost & latency telemetry

As a Platform engineer, I want AI calls telemetry (cost, latency, tokens, model), so that I optimise spend and SLA.

AC1 — Given any AI call, Then ai.cost_micro_usd, ai.model, ai.latency_ms, ai.tokens_in/out are emitted.
AC2 — Given cost exceeds expected band per model, Then an alert fires.
AC3 — Given I attribute cost per tenant, Then the dashboards reflect.
Services. ai-orchestrator-service.
Frontend. N/A.
DoD refs. Universal · AI · Observability.
Test types. Unit · Integration.
Complexity. S.

US-MEL-0161 — Status page & customer-facing communication

As a Platform Admin, I want a tenant-facing status page, so that tenants see incidents in real time.

AC1 — Given an incident is open, Then the status page reflects within 5 minutes.
AC2 — Given I post an update, Then subscribers are notified.
AC3 — Given the incident is resolved, Then the page is closed and the post-mortem linked when published.
Services. Platform.
Frontend. Public status page.
DoD refs. Universal · Compliance · Observability.
Test types. E2E.
Complexity. S.

23. Story Dependency Map

The dependency graph exposes critical-path stories that must land before downstream work can proceed. Build order is read top-to-bottom; cycles are forbidden.

From (must land first)	To (depends on it)	Reason
US-MEL-0001, 0002, 0005	US-MEL-0006…0011	Tenant + roles required before brand work
US-MEL-0003, 0004	US-MEL-0017 (meta listing)	A property must exist to be listed
US-MEL-0006…0011	US-MEL-0021	Tenant theme must be live for the booking site
US-MEL-0030, 0031	US-MEL-0032	Quote + hold before confirm
US-MEL-0032	US-MEL-0036, 0038, 0042	Confirm before check-in/checkout/payment paths
US-MEL-0042…0049	US-MEL-0044, 0045	Card/PayPal/Cash adapters before MFS
US-MEL-0050, 0051	US-MEL-0073…0077	Front-desk arrivals + check-in before lock issuance
US-MEL-0073…0080	US-MEL-0078 (offline encoder)	Vendor abstraction before offline issuance
US-MEL-0082, 0083, 0084	US-MEL-0085, 0086, 0087	Local store + sync API before conflict policies/outbox/UI
US-MEL-0083, 0084	US-MEL-0050…0058 (front-desk offline)	Sync engine before offline operations
US-MEL-0091…0098	US-MEL-0094, 0118 (drafted messages)	AI orchestration before messaging features
US-MEL-0099, 0100, 0101	US-MEL-0102, 0103, 0104	Token + preset + blocks before publish/review/config
US-MEL-0111, 0112	US-MEL-0113, 0114, 0115	Ingestion + marts before query API + cohorts + signals
US-MEL-0116…0120	US-MEL-0121	Channel + templates + audit before recipient prefs
US-MEL-0122, 0123	US-MEL-0124, 0125	Upload + isolation before optimization + lifecycle
US-MEL-0126, 0127	US-MEL-0128, 0129, 0130	JWT + RBAC before MFA/SSO/device binding
US-MEL-0133, 0134, 0135	US-MEL-0136, 0137, 0138	i18n + RTL + locale-aware primitives before workflow
US-MEL-0139…0142	US-MEL-0143	Tax + KYC + audit + residency before erasure
US-MEL-0144, 0145, 0146	US-MEL-0147…0161	Logs + metrics + traces before SLOs and downstream observability

Critical path for R1 (release wave 1): Tenant + IAM → Property + RoomTypes + Rooms → Inventory + Pricing → Quote/Hold/Confirm → Payment (cash + card) → Lock issuance + revoke → Front-desk arrivals + check-in/checkout → Sync engine + outbox → EOD reconciliation. Everything else is parallelizable along this spine.

24. Estimated Effort by Epic

Story complexity buckets: S = 2 dev-days, M = 5 dev-days, L = 12 dev-days, XL epic-only (split into stories). Effort below is a sum of story complexities; FE+BE counted as one engineering effort because the platform team is full-stack.

Epic	S	M	L	Approx. dev-days	Approx. dev-weeks (1 dev)	Approx. team-weeks (3 devs)
EP-MEL-01 Tenant Onboarding	1	9	2	71	14	5
EP-MEL-02 Consumer Meta Search	1	4	3	58	12	4
EP-MEL-03 Tenant Booking Experience	2	4	3	60	12	4
EP-MEL-04 Reservation Lifecycle	0	3	9	123	25	9
EP-MEL-05 Payment Gateway	0	5	3	61	13	5
EP-MEL-06 Front-Desk Operations	1	4	4	70	14	5
EP-MEL-07 Housekeeping	0	4	4	68	14	5
EP-MEL-08 Maintenance	0	6	0	30	6	2
EP-MEL-09 Lock & Key	0	2	6	82	17	6
EP-MEL-10 Offline-First Sync	1	3	4	65	13	5
EP-MEL-11 AI-Assisted Operations	0	3	5	75	15	5
EP-MEL-12 Theming Config	0	6	0	30	6	2
EP-MEL-13 Reporting	0	5	1	37	8	3
EP-MEL-14 Analytics Pipeline	0	3	2	39	8	3
EP-MEL-15 Notification	1	4	1	34	7	3
EP-MEL-16 File Storage	0	4	0	20	4	2
EP-MEL-17 IAM & Auth	0	2	5	70	14	5
EP-MEL-18 i18n & RTL	1	4	1	34	7	3
EP-MEL-19 Compliance	0	0	5	60	12	4
EP-MEL-20 Observability	3	9	4	99	20	7
Total	10	84	62	1186	241	82

Effort estimates assume one full-stack engineer fluent in the stack and a single tenant footprint. Multiplier of 1.4 applied historically once chain operators are in scope (R3). Quality gates (testing, security review, AI eval) are included; design and product discovery are not.

25. Phasing into Release Waves R1, R2, R3

We ship in three release waves. Each wave is a coherent product bundle that delivers value end-to-end and is gated by entry criteria, not calendar dates.

Wave R1 — "Operate One Hotel Online + Offline" (Phase 0/1)

Outcome. A single tenant in Afghanistan/Tajikistan/Iran can onboard, list on the meta layer, take direct bookings (cash + card), check guests in, issue keys, run housekeeping, close the day, and survive a 12-hour internet outage without losing data.

Entry criteria.

All 22 services have stub bundles.
ADRs 0001–0004 accepted.
CI/CD scaffolding (lint, typecheck, unit, integration, contract, OpenAPI diff) green on at least 5 services.
Sandbox + staging environments provisioned on GCP.

Wave R1 epics. EP-MEL-01, 02, 03, 04, 05, 06, 07, 09, 10, 12, 13, 15, 16, 17, 18, 19, 20.

Wave R1 exit criteria.

5 staging tenants seeded with realistic data; all P0 journeys (J-01 … J-12, J-19, J-20) green in nightly E2E.
Sync engine tolerates 24h offline with zero monetary loss in chaos tests.
AI HITL gate enforced; 0 bypasses in 7-day soak.
Coverage thresholds met per DEFINITION_OF_DONE.md.
Lock vendor adapters present for at least TTLock + generic Wiegand.
Payment adapters present for at least Stripe + cash + PayPal.
Pen-test pass with no critical or high findings.

Wave R2 — "AI-Native Operations + Multi-Property Tenants" (Phase 2)

Outcome. Tenants can run multi-property operations; AI assistance is on by default for forecasting, dynamic pricing, message drafting, and anomaly detection; analytics pipeline flowing into BigQuery; advanced housekeeping flows; full maintenance.

Entry criteria. R1 exit criteria met; ai-orchestrator-service Vertex+ONNX in production for 30 days; production telemetry shows healthy SLOs.

Wave R2 epics. EP-MEL-08, 11, 14 (full); enhancements to 06 (multi-property switcher), 12 (per-property theme overrides), 17 (chain operator SSO).

Wave R2 exit criteria.

AI suggestion acceptance rate ≥ 30% on pricing and housekeeping after 60 days.
BigQuery marts available for all P0 KPIs.
Multi-property tenant onboarding (J-14) green.
Cost dashboards show predictable per-tenant spend bands.

Wave R3 — "Globalisation + OTA + Channel Manager" (Phase 3)

Outcome. Expansion to GCC, South Asia, Sahel, East Africa; OTA channel manager adapter; advanced regulatory/tax for additional jurisdictions; SOC 2 readiness; full GDPR DSARs.

Entry criteria. R2 exit criteria met; tenant count ≥ 50; chain operators present.

Wave R3 epics. Extensions to EP-MEL-19 (jurisdiction matrix), EP-MEL-04 (OTA channel via reservation channel port), EP-MEL-15 (additional locales/channels), EP-MEL-20 (multi-region failover, advanced cost).

Wave R3 exit criteria.

OTA channel manager bidirectional sync stable.
Multi-region read failover validated in disaster-recovery drill.
DSAR fulfilment under 30 days end-to-end.

Wave-to-epic matrix

Epic	R1	R2	R3
EP-MEL-01	✓
EP-MEL-02	✓
EP-MEL-03	✓
EP-MEL-04	✓		+ OTA channel
EP-MEL-05	✓	+ MFS expansion
EP-MEL-06	✓	+ multi-property
EP-MEL-07	✓
EP-MEL-08		✓
EP-MEL-09	✓	+ Salto, Assa Abloy production
EP-MEL-10	✓
EP-MEL-11		✓
EP-MEL-12	✓	+ per-property overrides
EP-MEL-13	✓		+ jurisdiction add-ons
EP-MEL-14		✓
EP-MEL-15	✓		+ additional channels
EP-MEL-16	✓
EP-MEL-17	✓	+ chain SSO
EP-MEL-18	✓		+ new locales
EP-MEL-19	✓		+ jurisdiction matrix
EP-MEL-20	✓		+ multi-region

26. Cross-References

Per-service deep docs: see SERVICE_INDEX.md and services/<svc>/SERVICE_OVERVIEW.md.
Journeys realised by stories: docs/journeys/01-core-user-journeys.md (J-01 … J-22).
API contracts referenced from stories: docs/05-api-design.md and services/<svc>/API_CONTRACTS.md.
Event schemas: docs/04-event-driven-architecture.md and services/<svc>/EVENT_SCHEMAS.md.
Definition of Done gates referenced from DoD refs: docs/standards/DEFINITION_OF_DONE.md.
Testing strategy: docs/11-testing-strategy-qa.md — every story's Test types are operationalised there.
Naming conventions for IDs, error codes, sagas: docs/standards/NAMING.md, docs/standards/ERROR_CODES.md.
Architectural decisions: docs/architecture/ including ADR-0001 (core stack), ADR-0002 (multi-tenancy), ADR-0003 (Electron offline-first desktop), ADR-0004 (lock-integration abstraction).

1. Purpose & How To Read
- 1.1 What is an "epic" here
- 1.2 What is a "story" here
- 1.3 Naming & ID rules
- 1.4 Personas (canonical short list)
- 1.5 Cross-cutting acceptance (echoed per epic, never per story)
2. Epic Index
3. EP-MEL-01 — Tenant Onboarding & Configuration
- US-MEL-0001 — Owner self-signup with verified email & SMS
- US-MEL-0002 — Create primary tenant, pin home region, accept ToS
- US-MEL-0003 — Add the first property with geo, address, amenities
- US-MEL-0004 — Define room types and individual rooms
- US-MEL-0005 — Invite staff and assign roles
- US-MEL-0006 — Customise theme tokens (logo, colours, typography)
- US-MEL-0007 — Choose layout preset and content blocks
- US-MEL-0008 — Configure booking-flow rules per tenant
- US-MEL-0009 — Preview the public booking site as a guest
- US-MEL-0010 — Submit theme + config for marketing review
- US-MEL-0011 — Publish to make the site live
- US-MEL-0012 — Onboarding progress checklist with resume
4. EP-MEL-02 — Consumer Meta Search Layer
- US-MEL-0013 — Search by city + dates + guests
- US-MEL-0014 — Filter results by price band, amenities, rating
- US-MEL-0015 — Switch between list and map views (Leaflet)
- US-MEL-0016 — Compare up to three properties side-by-side
- US-MEL-0017 — Show price band & availability summary per result
- US-MEL-0018 — Hand off into tenant booking flow with state preserved
- US-MEL-0019 — Localise meta layer to RTL languages with currency conversion
- US-MEL-0020 — Anonymous favourites & recent searches
5. EP-MEL-03 — Tenant-Branded Booking Experience (Web + Mobile)
- US-MEL-0021 — Browse rooms and rate plans on the tenant site
- US-MEL-0022 — Adjust room count, dates, guests, options (+/–)
- US-MEL-0023 — Capture special requests and arrival time
- US-MEL-0024 — Pick payment method and confirm
- US-MEL-0025 — Multi-currency display with FX snapshot
- US-MEL-0026 — Multi-language booking flow (Pashto/Dari/Persian/Arabic/EN/FR/Tajik)
- US-MEL-0027 — Confirmation page with itinerary and add-to-calendar
- US-MEL-0028 — Resend confirmation across channels
- US-MEL-0029 — Booking funnel telemetry for analytics
6. EP-MEL-04 — Reservation Lifecycle (Quote → Confirm → Stay → Checkout)
- US-MEL-0030 — Generate price quote with TTL
- US-MEL-0031 — Place an inventory hold for a quote
- US-MEL-0032 — Confirm a reservation with payment outcome
- US-MEL-0033 — Modify reservation dates within policy
- US-MEL-0034 — Cancel reservation with policy enforcement
- US-MEL-0035 — Upsell offers (early check-in, late check-out, room upgrade)
- US-MEL-0036 — Check-in flow (front desk + guest mobile self-check-in)
- US-MEL-0037 — Mid-stay folio updates (charges, incidentals)
- US-MEL-0038 — Checkout flow with folio close and key revoke
- US-MEL-0039 — Walk-in booking from front desk
- US-MEL-0040 — No-show handling
- US-MEL-0041 — Group booking with single folio across multiple rooms
7. EP-MEL-05 — Payment Gateway with Cash on Arrival, MFS, Cards
- US-MEL-0042 — Card payment with 3DS
- US-MEL-0043 — PayPal payment
- US-MEL-0044 — Cash-on-arrival with deposit policy
- US-MEL-0045 — MFS (Mobile Financial Services) adapters
- US-MEL-0046 — Refund (full and partial)
- US-MEL-0047 — Chargeback handling
- US-MEL-0048 — Idempotent webhook processing
- US-MEL-0049 — End-of-day cash drawer reconciliation
8. EP-MEL-06 — Front-Desk Operations on Electron Desktop
- US-MEL-0050 — Arrivals board with today's expected guests
- US-MEL-0051 — One-tap check-in with key issuance
- US-MEL-0052 — Mid-stay reservation modifications
- US-MEL-0053 — Checkout flow with receipt printing
- US-MEL-0054 — Cash drawer open/close with audit
- US-MEL-0055 — Receipts as PDF in folio history
- US-MEL-0056 — Manager override pin for sensitive actions
- US-MEL-0057 — Quick guest lookup by phone, email, name, ID
- US-MEL-0058 — Shift handover summary
9. EP-MEL-07 — Housekeeping Coordination
- US-MEL-0059 — Auto-create cleaning task on checkout
- US-MEL-0060 — Drag-and-drop housekeeping board
- US-MEL-0061 — AI-suggested cleaning order
- US-MEL-0062 — Housekeeper kiosk mode
- US-MEL-0063 — Escalate to maintenance from housekeeping
- US-MEL-0064 — Status board with SLA timer
- US-MEL-0065 — Mid-stay cleaning request from guest
- US-MEL-0066 — Multi-language housekeeper instructions
10. EP-MEL-08 — Maintenance & Asset Management
- US-MEL-0067 — Create work order with severity, room, asset
- US-MEL-0068 — Assign and triage work orders
- US-MEL-0069 — Close work orders with parts and labor
- US-MEL-0070 — Preventive maintenance schedule
- US-MEL-0071 — Vendor coordination for outsourced repairs
- US-MEL-0072 — Asset registry with lifecycle status
11. EP-MEL-09 — Lock & Key Integration with Offline Issuance
- US-MEL-0073 — Issue mobile-key invite at check-in
- US-MEL-0074 — Encode RFID card at front desk
- US-MEL-0075 — PIN-based key for budget rooms
- US-MEL-0076 — Update key on date or room change
- US-MEL-0077 — Revoke key on early checkout / cancel / lost-key
- US-MEL-0078 — Offline encoder fallback
- US-MEL-0079 — Lock event anomaly detection
- US-MEL-0080 — Vendor adapter abstraction (TTLock, Salto, Assa Abloy, Wiegand)
- US-MEL-0081 — Lock vendor secret rotation
12. EP-MEL-10 — Offline-First Desktop with Sync Engine
- US-MEL-0082 — Local SQLite store with SQLCipher encryption
- US-MEL-0083 — Sync pull with cursor + delta
- US-MEL-0084 — Sync push with idempotency
- US-MEL-0085 — Per-aggregate conflict resolution policy
- US-MEL-0086 — Outbox flusher with FIFO ordering and backoff
- US-MEL-0087 — Sync status pill always visible
- US-MEL-0088 — Edge AI inference via ONNX Runtime Node
- US-MEL-0089 — Bandwidth-aware sync throttle
- US-MEL-0090 — Migration runner for SQLite schema
13. EP-MEL-11 — AI-Assisted Operations (Dynamic Pricing, Forecasting, Anomalies, Drafts)
- US-MEL-0091 — Dynamic pricing suggestions (HITL)
- US-MEL-0092 — Demand forecasting
- US-MEL-0093 — Anomaly detection (bookings, payments, locks)
- US-MEL-0094 — AI-drafted multi-language guest messages
- US-MEL-0095 — Upsell recommendation surfacing
- US-MEL-0096 — AI cost guardrails per tenant
- US-MEL-0097 — HITL gate enforcement
- US-MEL-0098 — Edge-vs-cloud equivalence for offered-both-ways capabilities
14. EP-MEL-12 — Multi-Tenant Theming & Per-Tenant Booking Flow Config
- US-MEL-0099 — Token-based theme bootstrap
- US-MEL-0100 — Layout presets
- US-MEL-0101 — Content block editor with i18n
- US-MEL-0102 — Preview vs Publish vs Rollback
- US-MEL-0103 — Marketing review workflow
- US-MEL-0104 — Per-tenant booking flow rule configuration
15. EP-MEL-13 — Reporting (Operational, Financial, Regulatory)
- US-MEL-0105 — Operational report templates (occupancy, ADR, RevPAR)
- US-MEL-0106 — Financial reports (folio, revenue, payment mix, taxes)
- US-MEL-0107 — Daily guest registration export (regulatory, where mandated)
- US-MEL-0108 — Scheduled runs and email delivery
- US-MEL-0109 — Multi-format export (PDF/CSV/Excel)
- US-MEL-0110 — Offline-cached recent reports
16. EP-MEL-14 — Analytics Pipeline (Events → BigQuery → Dashboards → AI Signals)
- US-MEL-0111 — Event ingestion to BigQuery
- US-MEL-0112 — Conformed marts (occupancy, revenue, channel)
- US-MEL-0113 — Query API for dashboards
- US-MEL-0114 — Cohort & funnel definitions
- US-MEL-0115 — AI input signals from analytics
17. EP-MEL-15 — Multi-Channel Notification (Email, SMS, WhatsApp, Push)
- US-MEL-0116 — Templates with i18n + RTL/LTR variants
- US-MEL-0117 — Scheduled notifications (pre-arrival, post-stay)
- US-MEL-0118 — AI-drafted message suggestions
- US-MEL-0119 — Delivery audit & retry
- US-MEL-0120 — Channel abstraction (email/SMS/WhatsApp/push)
- US-MEL-0121 — Recipient preference management
18. EP-MEL-16 — File Storage with Signed URLs, Virus Scan, Image Optimization
- US-MEL-0122 — Upload with signed URL & virus scan
- US-MEL-0123 — Tenant prefix isolation
- US-MEL-0124 — Image optimization & CDN
- US-MEL-0125 — Lifecycle policies (retention, archival)
19. EP-MEL-17 — Identity, Auth, Multi-Tenant RBAC, MFA, SSO, Device Binding
- US-MEL-0126 — JWT issuance & rotation
- US-MEL-0127 — RBAC with tenant scope
- US-MEL-0128 — MFA with TOTP and WebAuthn passkeys
- US-MEL-0129 — OIDC/SAML SSO for chain operators
- US-MEL-0130 — Device binding for desktop offline sessions
- US-MEL-0131 — Password reset & recovery
- US-MEL-0132 — Audit log of authn events
20. EP-MEL-18 — Multi-Language & RTL/LTR
- US-MEL-0133 — i18n bundle generation & loading
- US-MEL-0134 — RTL bidi-safe layouts
- US-MEL-0135 — Locale-aware date, number, currency
- US-MEL-0136 — Native OS menus per locale
- US-MEL-0137 — Locale-aware fonts
- US-MEL-0138 — Translation workflow for content
21. EP-MEL-19 — Compliance & Regulatory (Tax, KYC, Audit Logs)
- US-MEL-0139 — Tax engine with jurisdiction rules
- US-MEL-0140 — KYC for tenants in regulated markets
- US-MEL-0141 — Immutable audit log with daily Merkle anchoring
- US-MEL-0142 — Data residency enforcement
- US-MEL-0143 — GDPR-style data subject erasure (Phase 2)
22. EP-MEL-20 — Observability, Reliability, Cost Controls
- US-MEL-0144 — Structured logs with trace_id, tenant_id, request_id
- US-MEL-0145 — Metrics with tenant_id label
- US-MEL-0146 — Distributed traces with W3C traceparent
- US-MEL-0147 — SLOs and alerting
- US-MEL-0148 — Cost dashboards per tenant + per service
- US-MEL-0149 — Autoscaling policies for Cloud Run
- US-MEL-0150 — Synthetic monitoring of P0 journeys
- US-MEL-0151 — Error budget enforcement
- US-MEL-0152 — Feature flags with tenant scope
- US-MEL-0153 — Canary rollouts with auto-rollback
- US-MEL-0154 — Backup & restore for Cloud SQL
- US-MEL-0155 — Pub/Sub DLQ handling
- US-MEL-0156 — Runbook discoverability
- US-MEL-0157 — Incident timeline and post-mortems
- US-MEL-0158 — RUM (Real User Monitoring) for booking surfaces
- US-MEL-0159 — Sync telemetry (queue depth, conflict rate)
- US-MEL-0160 — AI cost & latency telemetry
- US-MEL-0161 — Status page & customer-facing communication
23. Story Dependency Map
24. Estimated Effort by Epic
25. Phasing into Release Waves R1, R2, R3
- Wave R1 — "Operate One Hotel Online + Offline" (Phase 0/1)
- Wave R2 — "AI-Native Operations + Multi-Property Tenants" (Phase 2)
- Wave R3 — "Globalisation + OTA + Channel Manager" (Phase 3)
- Wave-to-epic matrix
26. Cross-References

1. Purpose & How To Read​

1.1 What is an "epic" here​

1.2 What is a "story" here​

1.3 Naming & ID rules​

1.4 Personas (canonical short list)​

1.5 Cross-cutting acceptance (echoed per epic, never per story)​

2. Epic Index​

3. EP-MEL-01 — Tenant Onboarding & Configuration​

US-MEL-0001 — Owner self-signup with verified email & SMS​

US-MEL-0002 — Create primary tenant, pin home region, accept ToS​

US-MEL-0003 — Add the first property with geo, address, amenities​

US-MEL-0004 — Define room types and individual rooms​

US-MEL-0005 — Invite staff and assign roles​

US-MEL-0006 — Customise theme tokens (logo, colours, typography)​

US-MEL-0007 — Choose layout preset and content blocks​

US-MEL-0008 — Configure booking-flow rules per tenant​

US-MEL-0009 — Preview the public booking site as a guest​

US-MEL-0010 — Submit theme + config for marketing review​

US-MEL-0011 — Publish to make the site live​

US-MEL-0012 — Onboarding progress checklist with resume​

4. EP-MEL-02 — Consumer Meta Search Layer​

US-MEL-0013 — Search by city + dates + guests​

US-MEL-0014 — Filter results by price band, amenities, rating​

US-MEL-0015 — Switch between list and map views (Leaflet)​

US-MEL-0016 — Compare up to three properties side-by-side​

US-MEL-0017 — Show price band & availability summary per result​

US-MEL-0018 — Hand off into tenant booking flow with state preserved​

US-MEL-0019 — Localise meta layer to RTL languages with currency conversion​

US-MEL-0020 — Anonymous favourites & recent searches​

5. EP-MEL-03 — Tenant-Branded Booking Experience (Web + Mobile)​

US-MEL-0021 — Browse rooms and rate plans on the tenant site​

US-MEL-0022 — Adjust room count, dates, guests, options (+/–)​

US-MEL-0023 — Capture special requests and arrival time​

US-MEL-0024 — Pick payment method and confirm​

US-MEL-0025 — Multi-currency display with FX snapshot​

US-MEL-0026 — Multi-language booking flow (Pashto/Dari/Persian/Arabic/EN/FR/Tajik)​

US-MEL-0027 — Confirmation page with itinerary and add-to-calendar​

US-MEL-0028 — Resend confirmation across channels​

US-MEL-0029 — Booking funnel telemetry for analytics​

6. EP-MEL-04 — Reservation Lifecycle (Quote → Confirm → Stay → Checkout)​

US-MEL-0030 — Generate price quote with TTL​

US-MEL-0031 — Place an inventory hold for a quote​

US-MEL-0032 — Confirm a reservation with payment outcome​

US-MEL-0033 — Modify reservation dates within policy​

US-MEL-0034 — Cancel reservation with policy enforcement​

US-MEL-0035 — Upsell offers (early check-in, late check-out, room upgrade)​

US-MEL-0036 — Check-in flow (front desk + guest mobile self-check-in)​

US-MEL-0037 — Mid-stay folio updates (charges, incidentals)​

US-MEL-0038 — Checkout flow with folio close and key revoke​

US-MEL-0039 — Walk-in booking from front desk​

US-MEL-0040 — No-show handling​

US-MEL-0041 — Group booking with single folio across multiple rooms​

7. EP-MEL-05 — Payment Gateway with Cash on Arrival, MFS, Cards​

US-MEL-0042 — Card payment with 3DS​

US-MEL-0043 — PayPal payment​

US-MEL-0044 — Cash-on-arrival with deposit policy​

US-MEL-0045 — MFS (Mobile Financial Services) adapters​

US-MEL-0046 — Refund (full and partial)​

US-MEL-0047 — Chargeback handling​

US-MEL-0048 — Idempotent webhook processing​

US-MEL-0049 — End-of-day cash drawer reconciliation​

8. EP-MEL-06 — Front-Desk Operations on Electron Desktop​

US-MEL-0050 — Arrivals board with today's expected guests​

US-MEL-0051 — One-tap check-in with key issuance​

US-MEL-0052 — Mid-stay reservation modifications​

US-MEL-0053 — Checkout flow with receipt printing​

US-MEL-0054 — Cash drawer open/close with audit​

US-MEL-0055 — Receipts as PDF in folio history​

US-MEL-0056 — Manager override pin for sensitive actions​

US-MEL-0057 — Quick guest lookup by phone, email, name, ID​

US-MEL-0058 — Shift handover summary​

9. EP-MEL-07 — Housekeeping Coordination​

US-MEL-0059 — Auto-create cleaning task on checkout​

US-MEL-0060 — Drag-and-drop housekeeping board​

US-MEL-0061 — AI-suggested cleaning order​

US-MEL-0062 — Housekeeper kiosk mode​

US-MEL-0063 — Escalate to maintenance from housekeeping​

US-MEL-0064 — Status board with SLA timer​

US-MEL-0065 — Mid-stay cleaning request from guest​

US-MEL-0066 — Multi-language housekeeper instructions​