Backup and Restore

Relevant source files

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

• web/src/components/BackupManager.tsx
• android/app/src/main/kotlin/com/sovereign/communications/data/backup/DatabaseBackupManager.kt
• V1_COMPLETE_TASK_LIST.md
• TODO_AUDIT.md
• V1_PRODUCTION_IMPLEMENTATION_PLAN.md
• PLATFORM_PARITY_100_COMPLETE.md

The Backup and Restore feature is a cornerstone of the Sovereign Communications platform, designed to empower users with full control over their data. It allows users to export their entire dataset—including identities, contacts, messages, and settings—into a single, portable file. This file can be optionally encrypted with a user-provided password for security.

This functionality ensures data sovereignty, enabling users to move their data between devices or platforms, or simply to keep a secure offline copy. The feature is designed to be cross-platform, with a standardized export format that works across Web, Android, and iOS.

Architecture Overview

The backup process involves gathering all user-related data from the platform's local database, serializing it into a standardized JSON format, optionally encrypting it, and saving it as a file. The restore process reverses this, decrypting the file if necessary and importing the data back into the application's database.

The following diagram illustrates the high-level data flow for creating a backup.

Backup Data Format

All backups adhere to a standardized SCExportFormat schema to ensure cross-platform compatibility. The format is versioned to support future migrations and includes a timestamp of when the export was created.

Field	Type	Description
version	number	The schema version of the export file.
exportedAt	number	A timestamp indicating when the backup was created.
identities	Array	An array of the user's identities.
contacts	Array	The user's list of contacts.
conversations	Array	A list of all conversations.
messages	Array	All messages from all conversations.
peers	Array	Data about known peers in the mesh network.
routes	Array	Cached routing information.

Sources: V1_COMPLETE_TASK_LIST.md

Data Merging on Restore

During a restore operation, the system provides several strategies for handling conflicts with existing data.

Strategy	Description
OVERWRITE	Replaces existing data with the data from the backup.
MERGE	Combines the backup data with existing data, prioritizing newer entries.
SKIP	Ignores data from the backup if a conflicting entry already exists.

Sources: V1_COMPLETE_TASK_LIST.md

Encryption

To protect user data, backups can be encrypted with a user-supplied password. The encryption process uses a strong, industry-standard combination of PBKDF2 for key derivation and XChaCha20-Poly1305 for authenticated encryption.

The following diagram shows the encryption flow.

Implementation Status

While the encryption mechanism is defined, its implementation is not yet complete on all platforms.

• Web: The UI provides an option to set a password for an encrypted backup.
• Android: The DatabaseBackupManager.kt contains TODO comments indicating that the encryption and decryption logic is not yet implemented.

Sources: web/src/components/BackupManager.tsx:100-107, TODO_AUDIT.md:37-48

Platform Implementations

Web

The web application provides a comprehensive user interface for managing backups through the BackupManager React component.

Sources: web/src/components/BackupManager.tsx

UI and Options

The UI allows users to customize their backup by selecting which data to include.

Option	Default	Description
Include Messages	true	Includes all message history in the backup.
Include Contacts	true	Includes the user's contact list.
Include Settings	true	Includes application settings.
Encrypt Backup	true	Enables password-based encryption for the backup file.

Sources: web/src/components/BackupManager.tsx:6-9

Backup and Restore Flow

The user interaction is handled by the BackupManager.tsx component, which uses the useBackup hook to perform the core logic.

The following sequence diagram details the process of creating a backup on the web platform.

Restoring a backup is initiated by selecting a .json file. The restoreBackup function is called, and if the restore is successful, the page is reloaded to apply the new data state. A warning is displayed to the user that restoring will replace all current data.

Sources: web/src/components/BackupManager.tsx:35-46, 137-141

Android

On Android, the DatabaseBackupManager.kt class is responsible for handling backup and restore operations. It interfaces directly with the application's data layer.

Sources: android/app/src/main/kotlin/com/sovereign/communications/data/backup/DatabaseBackupManager.kt

The class diagram below shows its structure.

Key responsibilities include:

• createBackup: Gathers data from the Room database, serializes it, and writes it to a file specified by the user. It currently has a TODO to implement encryption.
• restoreBackup: Reads data from a specified file URI, deserializes it, and imports it into the database. It also has a TODO to handle decryption.

Sources: android/app/src/main/kotlin/com/sovereign/communications/data/backup/DatabaseBackupManager.kt:51, 77, TODO_AUDIT.md

iOS

The iOS implementation follows a similar pattern, utilizing a DataExporter to create the backup file and an importData function to handle the restore process. The backup is saved to the Files app, allowing the user to manage it directly.

Sources: V1_COMPLETE_TASK_LIST.md