Synchronization
The POS system uses a hybrid sync architecture combining WebSocket connections for real-time updates and HTTP for bulk data transfers. This design ensures stores operate independently while staying consistent with HQ.
How Sync Works
Each store server maintains a persistent WebSocket connection to the HQ sync server (on the port defined by SYNC_LISTEN_PORT). When data changes at HQ -- such as a new product, updated price, or role change -- the sync server pushes a notification to all connected stores over the WebSocket. The store then pulls the changed records via an HTTP API call.
In the other direction, stores push local data (sales transactions, Z Reports, inventory adjustments, transfer updates) to HQ on a regular interval (default: every 60 seconds) or immediately for certain high-priority events. This push happens over HTTP POST requests to the HQ sync API.
What Syncs and In Which Direction
HQ to Stores (downstream):
- Products (create, update, deactivate)
- Departments (create, update, deactivate)
- Tax rates (create, update)
- Users and role assignments
- Transfer records from other stores
Stores to HQ (upstream):
- Completed sales transactions
- Z Reports and ZZ Reports
- Inventory adjustments
- Transfer status updates (shipped, received)
- Register session data
Product and configuration data flows only from HQ to stores. Stores cannot modify products or tax rates locally. Transaction data flows only from stores to HQ. This unidirectional approach per data type prevents conflicts.
Offline Behavior
When a store loses connectivity to HQ, it continues operating normally. All POS Terminal and Store Manager functions work without interruption because they rely on the local PostgreSQL database. Data changes accumulate locally and are queued for sync.
When connectivity is restored, the store server detects the reconnection and begins syncing the queued data. Downstream changes from HQ (e.g., new products added while the store was offline) are also pulled during this catch-up period. The sync engine processes changes in chronological order to maintain consistency.
There is no time limit on offline operation. A store can function for days or weeks without syncing, and all accumulated data will eventually sync when connectivity returns. However, extended offline periods mean the store will not receive product updates, price changes, or new user assignments until it reconnects.
Troubleshooting Sync Issues
Check the sync status indicator in the Store Manager dashboard. A green indicator means the WebSocket connection is active. Red means disconnected. Common issues include:
- Firewall rules: Ensure the HQ sync port (default 3001) is open for WebSocket traffic.
- TLS certificate expiry: If using HTTPS/WSS, check that certificates are current.
- DNS resolution: The store must be able to resolve the HQ hostname.
- Token revocation: If the sync token was revoked in HQ Manager, generate a new one and update the store configuration.
Review the store server logs at logs/store-server.log for detailed sync error messages.