Offline Capabilities
Relevant source files
The following files were used as context for generating this wiki page:
DRX is designed as a privacy-first, local-first system that ensures business continuity even during internet outages. The offline capabilities allow users to process sales, manage customer data, and update inventory locally on the device. Data is automatically synchronized with the primary database once connectivity is restored.
The system utilizes a combination of IndexedDB for persistent local storage, a dedicated OfflineSyncManager to handle data reconciliation, and a React-based OfflineProvider to monitor network status and trigger synchronization workflows.
Sources: README.md:15-16, lib/utils/offline-sync.ts:1-10, scripts/help-center-data.ts:25-28
Local Data Architecture
The offline system relies on the browser's IndexedDB to store transaction logs and cached records. This allows the application to remain functional without a constant connection to Supabase.
IndexedDB Schema
The local database, named drx_crm_offline, is structured into several object stores to mirror the remote schema while managing synchronization state.
| Store Name | Key Path | Indices | Purpose |
|---|---|---|---|
transactions | id | synced, timestamp | Stores unsynced actions (POS sales, credit, etc.) |
inventory | id | - | Cached product and stock data |
customers | id | - | Cached customer profile information |
credit | id | - | Cached credit limit and balance data |
Sources: lib/utils/offline-sync.ts:5-15, lib/utils/offline-sync.ts:32-50
Transaction Structure
Every offline action is wrapped in an OfflineTransaction object, which includes metadata for retry logic and ordering.
interface OfflineTransaction {
id: string;
type: "pos_checkout" | "credit_extension" | "credit_payment" | "inventory_update";
data: any;
timestamp: number;
synced: number; // 0 = unsynced, 1 = synced
retry_count: number;
}
Sources: lib/utils/offline-sync.ts:17-24
Synchronization Logic
The OfflineSyncManager class orchestrates the movement of data between IndexedDB and the remote Supabase backend. It implements a queue-based system that processes transactions in the order they were created.
Data Flow Diagram
This diagram illustrates how a transaction is captured while offline and eventually reconciled with the server.
Sync Recovery and Maintenance
The manager handles failures through an incremental retry mechanism, capping attempts at 5 per transaction to prevent infinite loops on malformed data. It also performs periodic maintenance to purge historical local records.
- Retry Limit: Transactions exceeding 5 retries are flagged as failed and skipped in the next sync cycle.
- Cleanup: The
cleanupOldTransactions()method deletes synced records older than 7 days from the device. - RPC Mapping: Offline actions are mapped to specific PostgreSQL functions on the server, such as
process_pos_checkoutandextend_credit.
Sources: lib/utils/offline-sync.ts:133-162, lib/utils/offline-sync.ts:192-200
Network Monitoring and UI Feedback
The OfflineProvider component acts as a higher-order wrapper that provides real-time feedback to the user regarding their connection status and sync progress.
Connectivity Lifecycle
The provider uses the navigator.onLine API and window event listeners to detect transitions.
User Interface Indicators
A persistent status indicator is displayed in the bottom-right corner of the application to keep the user informed of the background sync status.
- Offline: Displays a
WifiOfficon and red background. - Syncing: Displays a spinning
RefreshCwicon when processing the queue. - Pending: Shows the count of transactions currently waiting in IndexedDB (polled every 5000ms).
- Online: Fades out to a minimal
Wifiicon to reduce visual noise.
Sources: components/providers/offline-provider.tsx:64-90
Operational Constraints and Best Practices
While offline mode ensures the POS remains operational, certain limitations and user responsibilities apply.
| Feature | Behavior | Source |
|---|---|---|
| Data Safety | Users MUST NOT uninstall the app while offline or local data will be lost. | scripts/help-center-data.ts:258-262 |
| Sales | POS transactions are stored locally and synced automatically upon reconnection. | README.md:15-16 |
| Inventory | Stock adjustments are captured locally but may face conflicts if server data changed. | scripts/help-center-data.ts:515-520 |
| Network Latency | If checkout fails due to a temporary network issue, the cart is preserved. | app/(app)/help/page.tsx:210-215 |
Sources: scripts/help-center-data.ts:258-262, app/(app)/help/page.tsx:210-215
Conclusion
The DRX offline system provides a robust fallback mechanism for retail environments where internet stability cannot be guaranteed. By utilizing IndexedDB for durable local storage and an RPC-based synchronization strategy, the platform maintains transactional integrity and financial accuracy across varying network conditions.