Skip to main content

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.

The sync hub (nu_pos_hub/) is a Node.js WebSocket broker that keeps multiple POS terminals in sync. It uses SQLite in WAL mode for persistence.

​
Architecture

┌──────────┐     ┌──────────┐     ┌──────────┐
│ Terminal  │────▶│          │────▶│  Odoo    │
│    A      │◀────│ Sync Hub │◀────│  Backend │
└──────────┘     │ (WS+SQL) │     └──────────┘
┌──────────┐     │          │
│ Terminal  │────▶│          │
│    B      │◀────│          │
└──────────┘     └──────────┘
Terminals connect via WebSocket. The hub:
  • Broadcasts order snapshots between terminals
  • Manages table locks (exclusive access per table)
  • Manages leases (terminal session tracking)
  • Forwards completed orders upstream to Odoo
  • Finalizes orders — when a terminal completes payment, the hub calls Odoo’s hub_finalize_snapshot to create the order with payments, NCF, and full fiscal processing

​
Protocol

The sync protocol (nu_pos_sync_protocol/) defines all message types using Zod schemas:
  • Terminal → Hub: ORDER_SNAPSHOT, TABLE_LOCK_ACQUIRE, TABLE_LOCK_RELEASE, HEARTBEAT, etc.
  • Hub → Terminal: ORDER_UPDATED, SYNC_INIT, TABLE_LOCK_GRANTED, TABLE_LOCK_DENIED, LEASE_GRANTED, etc.

​
Table locking

Each table has an exclusive lock. Only one terminal can edit a table’s orders at a time.
ParameterValue
Lock TTL45 seconds
Heartbeat interval15 seconds
Disconnect grace period10 seconds
Managers can force-acquire a lock held by another terminal.
Locking is disabled when offline — acquireTableLock returns granted immediately, and the system falls back to optimistic conflict resolution.

​
Transport abstraction

The frontend uses a SyncTransport interface (realtime/transport.ts) that supports two implementations:
  • directTransport — Polling + outbox queue (fallback mode)
  • hubTransport — WebSocket connection to the sync hub
The factory createTransport() reads nu_hub_enabled / nu_hub_url from bootstrap config to select the implementation.

​
Configuration

Enable the hub in Odoo POS configuration:
  • nu_hub_enabled — Toggle hub sync on/off
  • nu_hub_url — WebSocket URL of the hub
  • nu_hub_fallback_ip — Fallback IP when primary URL is unreachable