Skip to main content

J-20 — Offline Housekeeping Update from Desktop

One-liner: Network is down; housekeeping lead updates room status; statuses sync cleanly when connectivity returns.

1. Purpose​

When network is down, housekeeping lead still updates room statuses on the Electron desktop. Statuses cascade locally to the Front Desk view (same Electron app instance). On reconnect, all changes flush to housekeeping-service in correct order with audit-log entries. Outcome: zero loss of housekeeping work during outages; status consistent across local Electron screens; correct sync once online.

2. Persona Context​

  • Persona: Housekeeping Lead.
  • Surface: Electron Desktop (offline-primary).
  • Primary BFF: None online during outage.
  • Backing services (after reconnect): housekeeping-service, audit-service.
  • Preconditions: Electron app primer fresh.
  • Trigger: Network outage detected; lead continues working.

3. Entry Points​

#EntryNotes
1Outage during normal workDefault
2Planned offline shift (rural / weak link)Same UX

4. Screen-by-Screen Flow​

4.1 OfflineKanban (lead view)​

  • Layout: Same as J-19 §4.1 with offline pill prominent; "Pending: " counter; per-tile status shows local state.
  • Components: KanbanBoard, OfflineStatusPill.
  • Offline: Primary mode; reads from SQLite; AI banner hidden.
  • AI: Hidden offline.
  • Errors: Snapshot stale > 24 h -> blocking modal.
  • Loading: Sub-200 ms.
  • A11y: Offline pill announced; tiles tab-stop.
  • RTL: Mirror.
  • Perf: <= 200 ms.
  • Telemetry: frontend.housekeeping.offline_kanban_viewed.

4.2 OfflineTaskUpdateActions​

  • Layout: Same task actions (Start / Pause / Complete / Reassign / Inspect) operating on local state.
  • Components: Same as J-19 §4.2-4.4.
  • Offline: Primary; queued.
  • AI: None.
  • Errors: Conflict if local state differs at flush.
  • Loading: Sub-200 ms.
  • A11y: Action results announced.
  • RTL: Mirror.
  • Perf: <= 200 ms.
  • Telemetry: Same as J-19 with mode: offline.

4.3 SyncCenterScreen (post-reconnect)​

  • Layout: Same as J-07 §4.6 but for housekeeping events; conflict diff viewer for any concurrent server-side changes.
  • Components: SyncCenterTable, ConflictDiffViewer.
  • Offline: Lists local outbox.
  • AI: None on flush; P2 — conflict resolution suggestion.
  • Errors: Per-item retry; conflict resolution UX.
  • Loading: Spinner during flush.
  • A11y: Each row tab-stop; conflict diff structured.
  • RTL: Mirror.
  • Perf: Flush <= 30 s p95 typical.
  • Telemetry: frontend.sync.flush_started / flush_completed { okCount, errorCount }.

5. State Machine​

6. Data Requirements​

6.1 Local persistence​

  • SQLite housekeeping_tasks_local, outbox, audit_local.

6.2 Server reconciliation​

  • On reconnect, outbox flushes to housekeeping-service endpoints with X-Idempotency-Key.
  • Conflicts surfaced in Sync Center with diff.

6.3 Idempotency​

  • Per-update ULID; reused on retry.

7. AI Behavior​

  • Hidden offline.

8. Offline Behavior​

  • Primary mode of this journey.
  • All housekeeping operations work locally.
  • Front Desk view in same Electron app sees updated statuses immediately.

9. Error States​

ErrorTriggerUX shownRecoveryTelemetry
OFFLINE_PRIMER_STALESnapshot > 24 hBlocking modalReconnectfrontend.housekeeping.primer_stale
STATUS_CONFLICT_ON_FLUSHConcurrent server changeConflict UX in Sync CenterLead resolvesfrontend.sync.conflict { entity: hk_task }
OUTBOX_PARTIAL_FAILURESome events failSync Center shows errorsManual retryfrontend.sync.partial_failure

10. E2E Test Gates​

  • Composite gate G-HK-2: offline status updates -> reconnect -> outbox flush -> reconciliation.
  • Conflict variant: server-side change during outage.

11. Performance Requirements​

MetricTarget
Each action<= 200 ms local
Flush typical<= 30 s p95

12. Accessibility Requirements​

  • Offline pill announced.
  • Sync Center reachable via shortcut.
  • Conflict diff structured for screen readers.

13. Telemetry​

Frontend events​

  • frontend.housekeeping.offline_kanban_viewed
  • frontend.housekeeping.task_* events with mode: offline
  • frontend.sync.flush_* / conflict

Domain events emitted (after reconnect)​

  • melmastoon.housekeeping.task.status.changed.v1 (with originated_offline=true)
  • melmastoon.audit.recorded.v1

14. Success Criteria​

  • Zero loss of housekeeping work during outage.
  • Front Desk sees updated statuses immediately (same Electron instance).
  • Outbox flushes cleanly; conflicts surfaced explicitly.
  • Audit log entries correct after flush.

References​