MIGRATION_PLAN — bff-backoffice-service
Sibling: SERVICE_OVERVIEW · DATA_MODEL · DEPLOYMENT_TOPOLOGY · SYNC_CONTRACT
This BFF is Phase 1 greenfield for Ghasi Melmastoon — no legacy bff-backoffice-service predecessor. There is, however, a per-tenant onboarding ramp: each tenant transitions staff from a prior backoffice (a third-party PMS, a paper process, or a previous Ghasi-era tool) onto the Electron desktop backed by this BFF.
1. Scope
| In | Out |
|---|---|
| Per-tenant cutover from legacy backoffice to Electron desktop + this BFF | Domain data migration (handled by domain services' own MIGRATION_PLAN docs) |
| Device enrollment + DPoP key provisioning ramp | Device hardware procurement |
| AI suggestion + alert surface activation | Model training (ai-orchestrator-service) |
| Telemetry pipeline activation | KPI recomputation (analytics-service) |
| Sync handshake activation | Bulk sync engine (sync-service) |
| App-version floor management lifecycle | Auto-update server (electron-updater infra) |
2. Phases (per tenant)
Phase 0 ── tenant signed; iam + tenant + property data exists ─┐
│
Phase 1 ── operator roles + property scope provisioned ────────┤
│
Phase 2 ── pilot on 2 devices (front desk only) ───────────────┤
│
Phase 3 ── widen to all front-desk + housekeeping devices ────┤
│
Phase 4 ── add maintenance + GM devices ─────────────────────┤
│
Phase 5 ── full cutover; legacy backoffice decommissioned ────┘
| Phase | Duration | Exit |
|---|---|---|
| 0 | continuous | tenant + property + operator data exists |
| 1 | 1 week | operator → property mapping verified by CSM |
| 2 | 2 weeks | 2 devices live; 14 days of incident-free operation |
| 3 | 2 weeks | All front-desk + housekeeping; conversion parity vs legacy |
| 4 | 2 weeks | Maintenance + GM |
| 5 | 1 week | Legacy decommissioned with operator sign-off |
3. Pre-cutover preparation per tenant
3.1 Operator + property data
CSM works with tenant to populate:
- Operator accounts in
iam-servicewith MFA enrolled. - Operator → property scope in
tenant-service. - Operator role assignments (front_desk, housekeeping, maintenance, GM, etc.).
- Per-tenant policy flags (MFA scope thresholds, AI surfaces, theme bundle).
3.2 Device enrollment
For each device:
Hotel IT installs the signed Electron installer.
Operator signs in for the first time.
iam-service issues a device-enroll challenge:
- operator authenticates with primary credential + MFA
- desktop generates device key pair via @ghasi/device-key-gen
- public key + device metadata sent to iam-service.deviceEnroll
- iam-service stores device in registry; returns deviceId + cnf.jkt
- private key persisted to OS keychain via keytar
- access + refresh tokens minted bound to device key
This BFF is NOT on the enrollment path. After enrollment, every request to this BFF carries DPoP.
3.3 Device baseline state
Before enrollment, hotel IT must:
- Update OS to supported version (Win10 21H2+, macOS 13+, Ubuntu 22.04+).
- Install OS-level keychain provider (libsecret on Linux).
- Whitelist
backoffice.melmastoon.ghasi.ioandsync.melmastoon.ghasi.ioin any corporate firewall. - Allow SSE long-poll connections on the proxy (or accept polling fallback).
- Configure printer + lock peripherals.
3.4 Telemetry channel verification
For each new tenant:
- Confirm
melmastoon.bff.backoffice.session.opened.v1events arrive in BigQuery. - Confirm tenant appears in "Operator effectiveness" dashboard within 24 h.
- Calibrate per-tenant alerts after 14 days of baseline.
3.5 AI surface activation
Per AI_INTEGRATION §9:
ai.surfaces.enabled[<tenantId>] = trueonce orchestrator has trained tenant-specific model + risk-reviewed.- Initial categories conservative (
audit_anomaly,housekeeping_reorder); broaden after 30 d of decision telemetry.
4. Cutover sequence (per tenant)
4.1 Pilot (Phase 2)
[T-7d] CSM + tenant agree pilot devices and pilot duration
[T-7d] Devices imaged + Electron installer pushed via hotel IT
[T-3d] Operators trained (1-day session per device cohort)
[T-1d] Day-end run on legacy backoffice; export historical state
[T-0] Pilot operators sign in; this BFF on the path
Legacy backoffice still available read-only as safety net
[T+14d] Pilot retrospective; go/no-go for Phase 3
4.2 Wider rollout (Phase 3+)
Same cadence per cohort. CSM and SRE on-call coordinate via shared war-room channel for the first 24 h of each phase.
4.3 Cutover (Phase 5)
Final shift on legacy backoffice. Full handoff to Electron + this BFF. Legacy access removed (or turned read-only for 90 d safety window).
5. Rollback
Tenant-scoped rollback plays:
| Trigger | Action |
|---|---|
| Mass DPoP failure on a tenant cohort | tenant.bff_backoffice_enabled = false flag → BFF returns 503; desktop falls into offline mode; tenant returns to legacy backoffice |
| Catastrophic data divergence | Pause sync handshake for tenant; tenant operates offline; operations team triages |
| Lock-action audit gap | Halt lock proxy globally; investigate; per-tenant resume after fix |
| Force-logout storm | Pause force-logout broadcast; iam-service revocations effective on next refresh |
6. Multi-tenant rollout calendar
Tenants onboard in waves to control blast radius:
| Wave | Tenants | Start |
|---|---|---|
| Wave 1 (canary) | 2 design partners | Week 1 |
| Wave 2 (early adopters) | 5 tenants | Week 5 |
| Wave 3 (early majority) | 15 tenants | Week 12 |
| Wave 4 (general availability) | remainder | Week 20 |
Each wave gates on prior-wave SLOs for 14 days.
7. Schema migrations (this service)
| Migration | Description |
|---|---|
0001_init.sql | outbox, inbox, idempotency, schema_migrations |
0002_device_sync_status.sql | DeviceSyncStatus table |
0003_operator_preferences.sql | OperatorPreferences mirror |
0004_operator_activity.sql | Activity ledger |
0005_alert_ack_log.sql | Alert acknowledgements |
0006_ai_decision_log.sql | AI decisions |
0007_lock_action_proxy_audit.sql | Lock-action audit |
0008_offline_action_queue_hints.sql | OfflineActionQueueHint |
0009_indexes_pass_2.sql | Index tuning after first load test |
0010_rls_policies.sql | RLS on tenant-scoped tables |
0011_seed_dev_tenants.sql | (dev/seed only) |
0012_outbox_partitioning.sql | (Phase 2) outbox monthly partitioning |
All Drizzle-managed; idempotent; rollback files where reversible.
8. Telemetry-pipeline activation
For each new tenant:
- Confirm
melmastoon.bff.backoffice.session.opened.v1lands in BigQuery. - Verify tenant appears in operator-effectiveness dashboard within 24 h.
- Verify alerts fire correctly on synthetic AI decision + lock action.
- Calibrate per-tenant alert thresholds after 14 d of baseline.
9. App-version-floor lifecycle
The BFF can refuse versions below a floor (MELMASTOON.SYNC.VERSION_BLOCKED). This is a powerful operational lever:
| Step | Notes |
|---|---|
| 1. Identify a critical bug requiring forced upgrade | E.g., audit-log gap, security defect |
| 2. Ship desktop release fixing it; ensure auto-update reaches > 90% of fleet | Track via heartbeat appVersion; usually 14 d window |
| 3. Coordination meeting: FE Platform + Desktop + SRE + CSM | Identify holdouts |
| 4. CSM contacts holdouts; assists with manual update | If hotel IT delays |
| 5. Set advisory floor (warn but don't block) | desktop shows banner |
| 6. Advisory window 7 d | escalate to GMs |
| 7. Set enforcing floor | desktop blocked; offline-mode still works for queued reads |
| 8. Final outreach to remaining holdouts | rare |
The floor is set in bff-backoffice-flags Memorystore key with 30 s refresh; rollback is instant (lower the floor again).
10. Decommission of legacy backoffice (per tenant)
Tenant chooses; we recommend:
- Keep legacy read-only for 90 d safety window.
- Track legacy access; once < 1% over 7 d, propose decommission to CSM.
- Tenant decommissions; we update tenant CMS + operator training material.
11. Phase 2+ candidates (out of scope here)
- Mobile backoffice surface (separate BFF if introduced).
- Web backoffice surface (probably consolidated with this BFF v2 with browser-cookie auth).
- Multi-property device sessions (currently single-property primary).
- Voice-driven workflows (would require separate AI surface contract).