Skip to main content

J-14 — Onboard Chain (Multi-Property Tenant)

One-liner: A small chain onboards one tenant with multiple properties, shared theme, and per-property overrides.

1. Purpose​

A small chain (3-15 properties) onboards one Melmastoon tenant with multiple properties, a shared theme, per-property overrides, and centralised reporting. Outcome: chain tenant with N properties live; property-level rate plans configurable independently; chain dashboard available.

2. Persona Context​

  • Persona: Chain operator (HQ).
  • Surfaces: Control Plane Web; Electron Desktop (per property).
  • Primary BFF: bff-control-plane-service.
  • Backing services: tenant-service, theme-config-service, payment-providers-adapter (per-property accounts), audit-service.
  • Preconditions: Tenant created (J-13 path) with chain mode enabled.
  • Trigger: "Add property" CTA from Chain Settings.

3. Entry Points​

#EntryNotes
1"Add property" CTADefault
2Bulk import (CSV)P2
3Sales-onboarding wizardPre-filled

4. Screen-by-Screen Flow​

4.1 ChainSettingsScreen​

  • Layout: Tabs: Properties / Shared theme / Reports / Users / Roles.
  • Components: Tabs, PropertyList.
  • Offline: n/a.
  • AI: None.
  • Errors: Insufficient permissions -> redirect.
  • Loading: Sub-200 ms.
  • A11y: Tabs follow WAI ARIA tab pattern.
  • RTL: Mirror.
  • Perf: <= 200 ms.
  • Telemetry: frontend.chain.settings_viewed.

4.2 AddPropertyWizard (4 steps)​

  • Layout: Step 1 property identity; Step 2 theme overrides (inherits chain theme; overrides allowed); Step 3 payment provider account (per-property); Step 4 publish.
  • Components: Reuses J-13 components with chain-aware UI.
  • Offline: Disabled.
  • AI: Phase 2 — auto-fill from "similar property" template.
  • Errors: Validation per step.
  • Loading: Each step <= 200 ms.
  • A11y: Step indicator announced.
  • RTL: Mirror.
  • Perf: Total wizard <= 5 min user time.
  • Telemetry: frontend.chain.property_added { propertyId }.

4.3 SharedThemeOverridesScreen​

  • Layout: Inheritance tree; per-property overrides table; "Apply to all" / "Override here" controls.
  • Components: InheritanceTree, OverrideTable.
  • Offline: n/a.
  • AI: None.
  • Errors: Override conflict warnings.
  • Loading: Sub-200 ms.
  • A11y: Tree is keyboard-navigable per WAI ARIA tree pattern.
  • RTL: Mirror.
  • Perf: <= 200 ms.
  • Telemetry: frontend.chain.theme_override_changed.

5. State Machine​

6. Data Requirements​

6.1 Server state​

  • POST /api/v1/tenants/:id/properties
  • PATCH /api/v1/themes/:tenantId/properties/:propertyId/overrides
  • GET /api/v1/tenants/:id/dashboard

6.2 Local persistence​

  • Form drafts in IndexedDB.

6.3 Idempotency​

  • All mutations carry X-Idempotency-Key.

7. AI Behavior​

n/a in P1; P2 — "similar property" template suggestion.

8. Offline Behavior​

  • Requires online.

9. Error States​

ErrorTriggerUX shownRecoveryTelemetry
OVERRIDE_CONFLICTTwo overrides clashInline warningUser resolvesfrontend.chain.override_conflict
PROVIDER_PER_PROPERTY_FAILEDProvider connect failureRetry bannerUser retriesfrontend.chain.provider_failed

10. E2E Test Gates​

  • Composite gate G-CP-2: add property -> theme override -> publish -> live.
  • Override inheritance verified.

11. Performance Requirements​

MetricTarget
Each step<= 200 ms
Wizard total<= 5 min user time

12. Accessibility Requirements​

  • All keyboard-completable.
  • Inheritance tree accessible.

13. Telemetry​

Frontend events​

  • frontend.chain.settings_viewed
  • frontend.chain.property_added { propertyId }
  • frontend.chain.theme_override_changed

Domain events emitted​

  • melmastoon.tenant.property.added.v1
  • melmastoon.theme.override.changed.v1
  • melmastoon.audit.recorded.v1

14. Success Criteria​

  • Add-property wizard completes <= 5 min user time per property.
  • Inheritance + override behaviour matches spec.
  • Chain dashboard reflects new property within 60 s.

References​