Frontend integration

Documentation Index

Fetch the complete documentation index at: https://docs.laportenard.com/llms.txt

Use this file to discover all available pages before exploring further.

1. State machine (syncMachine) — Tracks transport state, lease state, and outbox depth
2. Provider (RealtimeProvider) — Creates the transport, wires event handlers, bridges to UI state
3. UI components — Visual indicators for sync status, conflict dialogs, lease notifications

​

Sync state machine

​

States

                    ONLINE
                   +------+
          +------->|      |<--------+
          |        +--+---+        |
          |           |            |
       ONLINE    TRANSPORT_     TRANSPORT_
                 RECONNECTING  CONNECTED
          |           |            |
          |           v            |
          |     RECONNECTING       |
          |        +------+        |
          |        |      |--------+
          |        +--+---+
          |           |
       OFFLINE   TRANSPORT_
                 DISCONNECTED
          |           |
          v           v
        OFFLINE    OFFLINE
       +------+   (from reconnecting)
       |      |
       +------+
          |
        ONLINE
          |
          v
       HUB_OFFLINE
       +------+
       |      |---> ONLINE (on TRANSPORT_CONNECTED)
       |      |---> RECONNECTING (on TRANSPORT_RECONNECTING)
       +------+

​

Context

interface SyncContext {
  isOnline: boolean;
  lastSyncAt: number | null;
  lastSeenSyncId: number;
  appliedCount: number;
  lastError: string | null;
  transportMode: "direct" | "hub";
  hubUrl: string | null;
  leaseHeld: string | null;
  outboxDepth: number;
  connectedTerminals: number;
  transportState: TransportState;
}

​

Events

​

RealtimeProvider

​

Event wiring

• transport.onStateChange() → Maps transport state to sync machine events
• transport.onConflict() → Shows conflict dialog via SyncUIProvider
• transport.onLeaseRevoked() → Sends LEASE_LOST to sync machine
• transport.onOrderUpdated() → Applies remote order update to local state
• transport.onReconnecting() → Sets isReconnecting in SyncUIProvider (shows overlay)
• transport.onReconnected() → Clears isReconnecting (hides overlay)
• transport.onStateChange() to disconnected while isReconnecting → Sets reconnectionFailed (session expired)
• Browser online/offline events → ONLINE/OFFLINE to sync machine

​

Provider tree

<SyncUIProvider>          // Sync UI state (conflicts, lease notifications)
  <RealtimeProvider>      // Transport lifecycle, event handling
    <PosProvider>         // Order state, reducer
      <App />
    </PosProvider>
  </RealtimeProvider>
</SyncUIProvider>

​

UI components

​

SyncStatusIndicator

​

ConflictDialog

• “Load Latest” → Calls reconcile() with accept_remote strategy
• “Keep Mine” → Dismisses dialog, allows user to manually resolve

​

SyncOverlay

• Renders ConflictDialog when conflict is non-null
• Renders ReconnectionOverlay for sleep/wake recovery (see below)
• Shows a destructive toast when leaseRevoked is non-null (“Manager took over this order”)

​

ReconnectionOverlay

​

TableLockedDialog

• “Dismiss” — Close dialog, release any pending lock
• “Take Over” (managers only) — Force-acquire the lock

​

TableLockGuard

• Releases the lock on unmount
• Re-acquires the lock after WebSocket reconnect
• Redirects to the floor plan if the lock is revoked

​

Bridge components

​

HubOrderBridge

• Outbound: Builds OrderSnapshotData from active order on every state change → sends ORDER_SNAPSHOT via transport (with hash-based change detection to avoid redundant sends)
• Inbound SYNC_INIT: Applies full order reconciliation on connect (gated on hydrated to wait for IndexedDB restore)
• Inbound ORDER_UPDATED: Applies remote snapshots via applyRemoteSnapshot({ posReference, snapshot }) — auto-creates orders for the active table, closes orders with paid/closed status or empty lines
• Lease lifecycle: Acquires lease when active order has items + posReference, releases on switch/unmount
• Deletion detection: Sends closed snapshot to hub when local orders are removed

​

FloorPlanSyncBridge

• Inbound SYNC_INIT: Full reconciliation (same as HubOrderBridge)
• Inbound ORDER_UPDATED: Applies remote snapshots so table occupation status stays current across terminals. Closes orders with paid/closed status or empty lines

​

FloorPlanStructureSyncBridge

• Inbound FLOOR_PLAN_CHANGED: Updates floor plan table positions and structure when another terminal edits the layout
• Outbound: Sends FLOOR_PLAN_UPDATE when the current terminal saves layout changes

​

How everything connects

Bootstrap config (Odoo)
  |
  v
createTransport() --> directTransport or hubTransport
  |
  v
RealtimeProvider
  |
  +-- transport.onStateChange() --> syncMachine (TRANSPORT_* events)
  +-- transport.onConflict()    --> SyncUIProvider.showConflict()
  +-- transport.onLeaseRevoked()--> SyncUIProvider.notifyLeaseRevoked()
  +-- transport.onOrderUpdated()--> apply to local order state
  +-- transport.onTableLocksState()--> update floor plan lock indicators
  +-- transport.onTableLockRevoked()--> TableLockGuard redirects to floor plan
  |
  v
syncMachine context
  |
  v
SyncStatusIndicator (reads transportState, outboxDepth, lastError)
ConflictDialog      (reads SyncUIProvider.conflict)
SyncOverlay         (reads SyncUIProvider.leaseRevoked, shows toast)

​

i18n

{
  "sync": {
    "connected": "Synced",
    "connecting": "Connecting",
    "reconnecting": "Reconnecting",
    "hubOffline": "Hub Offline",
    "offline": "Offline",
    "error": "Sync Error",
    "pendingItems": "{count} pending",
    "conflictTitle": "Version Conflict",
    "conflictAcceptRemote": "Load Latest",
    "conflictKeepLocal": "Keep Mine",
    "leaseRevokedTitle": "Order Taken Over",
    "leaseRevokedGeneric": "Another user took over this order",
    "reconnectionTitle": "Restoring connection...",
    "reconnectionSubtitle": "Please wait while we reconnect to the server",
    "reconnectionFailed": "Session expired. Redirecting to login..."
  }
}