Offline Support and Sync Engine

Relevant source files

The following files were used as context for generating this wiki page:

• V1_PRODUCTION_IMPLEMENTATION_PLAN.md
• V1_READINESS_REPORT.md
• V1_COMPLETENESS_AUDIT.md
• PRODUCTION_READINESS_AUDIT.md
• V1_READINESS.md
• TODO_AUDIT.md

The Offline Support and Sync Engine is a critical component of the Sovereign Communications platform, designed to ensure message reliability and enable communication in disconnected or asynchronous environments. Its primary purpose is to store outgoing messages that cannot be delivered immediately and retry sending them later. This system is fundamental to the "Sneakernet" capability, where data can be physically transported between offline devices.

The engine is built around a persistent OfflineQueue that manages message storage, retries with exponential backoff, and queue size limits. This ensures that no data is lost if the application restarts or loses connectivity. The implementation spans the shared @sc/core library and has specific integrations on each platform (Web, Android, iOS) to handle persistence and background processing.

Core Architecture: The OfflineQueue

The heart of the offline system is the OfflineQueue class, designed to be implemented in the @sc/core library. It provides a robust mechanism for enqueuing, processing, and retrying messages that fail to send.

Sources: V1_PRODUCTION_IMPLEMENTATION_PLAN.md, PRODUCTION_READINESS_AUDIT.md

Class Design

The OfflineQueue class manages the lifecycle of messages that are waiting for delivery.

Queued Message Data Structure

When a message is added to the queue, it is stored using the QueuedMessage interface, which includes metadata for managing its delivery.

Field	Type	Description
id	string	A unique identifier for the queued message.
recipientId	string	The ID of the intended recipient.
content	string	The message content.
attachments	File[] (optional)	Any file attachments associated with the message.
timestamp	number	The original time the message was created.
retries	number	The number of times a delivery attempt has been made.
nextRetry	number	The timestamp for the next scheduled retry attempt.
maxRetries	number	The maximum number of retries before the message is discarded.

Sources: V1_PRODUCTION_IMPLEMENTATION_PLAN.md

Message Processing and Retry Logic

The OfflineQueue employs a retry mechanism with exponential backoff to handle transient network failures without overwhelming the system.

1. Enqueue on Failure: When a message fails to send, it is enqueued into the persistent queue.
2. Process Queue: The processQueue method periodically checks for messages whose nextRetry timestamp is in the past.
3. Attempt Send: It attempts to send each pending message using a provided sendFn.
4. Handle Success: If the message is sent successfully, it is deleted from the queue.
5. Handle Failure: If the send fails again, the scheduleRetry method is called.
   • The retries count is incremented.
   • If retries is less than maxRetries, a new nextRetry time is calculated using exponential backoff (e.g., 1s, 2s, 4s, 8s, 16s).
   • If retries reaches maxRetries, the message is discarded from the queue to prevent it from being stuck indefinitely.

Sources: V1_PRODUCTION_IMPLEMENTATION_PLAN.md, PRODUCTION_READINESS_AUDIT.md

This diagram illustrates the message processing flow.

Configuration

The behavior of the queue is governed by several key parameters.

Parameter	Default Value	Description
MAX_QUEUE_SIZE	1000	The maximum number of messages that can be stored in the queue.
MAX_RETRIES	5	The maximum number of delivery attempts for a single message.
INITIAL_BACKOFF	1000 ms	The initial delay in milliseconds for the first retry.

Sources: V1_PRODUCTION_IMPLEMENTATION_PLAN.md, V1_COMPLETENESS_AUDIT.md

Platform-Specific Implementations

While the core logic resides in @sc/core, each platform is responsible for providing persistent storage and integrating the queue into its network layer.

Web Platform

The web implementation leverages IndexedDB for persistence, as confirmed by multiple audit documents.

• Persistence: An offlineQueue object store is created in IndexedDB to persistently store QueuedMessage objects. This is managed via web/src/storage/schema-validator.ts.
• Integration: The web/src/hooks/useMeshNetwork.ts hook is responsible for integrating the queue. When a message send operation fails, the message is enqueued. The hook also contains logic to periodically process the queue.
• "Sneakernet" UI: Initially, the web app lacked a UI to use the "Sneakernet" feature (exporting/importing data), which was identified as a gap. This functionality relies on exportAllData and importData methods in the database layer. A BackupManager.tsx component was later added to address this.

Sources: V1_READINESS_REPORT.md, V1_COMPLETENESS_AUDIT.md, V1_READINESS.md

Android Platform

The Android implementation was initially identified as having persistence but lacking the orchestration to connect the UI with the backend components.

• Persistence: The BLEStoreAndForward.kt component was noted for its ability to persist a queue to JSON, indicating an early form of offline storage. The final implementation uses the Room database.
• Integration: The MeshNetworkManager.kt was initially a stub but was later implemented to connect the UI, database, and networking components. The ChatViewModel.kt integrates message queuing and retry logic.
• Status: The platform was brought to parity, with a complete offline queue system integrated into the MeshNetworkService.

Sources: V1_READINESS_REPORT.md, V1_COMPLETENESS_AUDIT.md, TODO_AUDIT.md

iOS Platform

The iOS app initially had a major gap, lacking a persistent "store-and-forward" queue for outgoing messages.

• Initial State: The BluetoothMeshManager.swift was robust for BLE, but there was no system to save messages if a peer was unavailable.
• Remediation: This gap was addressed to achieve platform parity. The final implementation includes a persistent queue, likely using Core Data, and leverages background task support to process the queue even when the app is not in the foreground.

Sources: V1_READINESS_REPORT.md, V1_COMPLETENESS_AUDIT.md

Sequence of an Offline Message

This sequence diagram shows how a message is handled when the recipient is initially offline.

Conclusion

The Offline Support and Sync Engine is a foundational element of the SC platform's resilience and decentralization promise. By implementing a persistent, retry-capable OfflineQueue across all platforms, the system guarantees eventual message delivery even in challenging network conditions. This architecture not only makes asynchronous communication reliable but also enables the unique "Sneakernet" feature, allowing for true offline data sovereignty and exchange. The successful integration of this engine was a critical step toward the V1.0 production release.