Data Synchronization in SailPilot
The Data Synchronization section of SailPilot’s documentation outlines the strategies and mechanisms employed for ensuring consistent data flow between the app’s frontend and backend, crucial in an offline-first application.
Synchronization Overview
Provides a high-level view of the data synchronization strategy in SailPilot.
Discusses the general flow of data between the offline storage and the server.
Connection Management
SailPilot implements an offline-first approach, and an essential part of this strategy is to effectively manage network connectivity status. The ConnectionStatusSingleton class is responsible for this functionality.
Purpose
The ConnectionStatusSingleton class:
Monitors network connectivity changes.
Provides a single source of truth regarding the network connection status.
Notifies other parts of the application when the connection status changes.
Key Methods
initialize: Sets up the listener for connectivity changes and initiates a connection check.
checkConnection: Performs an HTTP request to determine if the server is reachable, indicating if the device is online.
_connectionChange: Callback that reacts to changes in network connectivity, triggering data synchronization if the connection is restored.
Usage
Throughout the application, connectionStatus (the instance of ConnectionStatusSingleton) can be used to subscribe to connectivity updates or check the current network status. This enables the app to make intelligent decisions about when to use local data and when to sync with the server.
Transaction Model
The Transaction model in SailPilot is designed to record and track operations that need to be synchronized with the server. This model is part of the app’s data synchronization mechanism, particularly vital for its offline-first functionality.
Structure
operation: Indicates the type of operation (e.g., ‘create’, ‘update’, ‘delete’).
entityType: Specifies the type of entity the operation affects (e.g., ‘User’, ‘UserProfile’).
entityId: The unique identifier of the entity involved in the transaction.
data: Any additional data relevant to the operation.
timestamp: The date and time when the transaction was created.
status: Tracks the current status of the transaction, such as ‘pending’ or ‘completed’.
errorMessage: Stores information about any errors encountered during the transaction processing.
Usage
Transactions are created whenever there is a change in user data or other entities that need to be reflected on the server. Each transaction records sufficient details to allow the DataSyncManager to process and synchronize these changes when the app is online.
Note
The Transaction model is key to maintaining data integrity and consistency between the local storage and the server, ensuring a seamless user experience in SailPilot even during intermittent connectivity.
DataSyncManager
The DataSyncManager class is a cornerstone of the SailPilot application’s data synchronization process. It is responsible for managing the synchronization of data between the local database and the remote server, particularly vital in ensuring data consistency in offline and online scenarios.
Functionality
Process Queue: Initiates the process of checking and handling synchronization tasks. It ensures the app only attempts to synchronize data when there is an active internet connection.
Transaction Management: Works in conjunction with the Transaction model to handle data operations that require synchronization.
Periodic Synchronization: Implements a timer to periodically trigger synchronization, ensuring data consistency over regular intervals.
Error Handling and Status Updates: Manages error scenarios and updates transaction statuses accordingly, maintaining a reliable record of synchronization activities.
Key Methods
init(): Initializes necessary components or settings for synchronization.
processQueue(): Processes the queue of pending transactions, sorting them by timestamp and handling each accordingly.
_syncUser(): A specific method for synchronizing user-related data. Can be extended or modified for other entity types.
syncData(): General method for syncing data to the server, handling HTTP requests and responses.
startSync(): Manually triggers the synchronization process.
startPeriodicSync(): Starts the periodic synchronization process using a timer.
stopPeriodicSync(): Stops the periodic synchronization process.
Usage
The DataSyncManager is utilized throughout the SailPilot app to ensure that any changes made in offline mode are properly and securely synchronized to the server once connectivity is restored. It plays a pivotal role in maintaining data integrity and user experience in an offline-first application.
Note
This class demonstrates SailPilot’s commitment to seamless data synchronization, providing a robust mechanism to handle offline data changes and ensuring these changes are reflected on the server as soon as connectivity allows.
Periodic Synchronization
In SailPilot, the periodic synchronization of data plays a crucial role in maintaining the application’s data integrity and user experience. This mechanism ensures that the app’s local data is consistently updated with the server, especially after changes made during offline usage.
Functionality
Triggered on User Login: The DataSyncManager’s periodic synchronization process is initiated as part of the user login workflow. When a user successfully logs in, the login method in the AuthState class calls dataSyncManager.startPeriodicSync(). This action sets off a routine that periodically checks for and syncs any pending data changes with the server.
Halts on User Logout: To align with the application’s lifecycle and user sessions, periodic synchronization is halted when a user logs out. The logout method in the AuthState class calls dataSyncManager.stopPeriodicSync(), effectively stopping the periodic sync process. This ensures that synchronization only occurs during active user sessions, optimizing resource usage and aligning data sync with user activity.
Importance
Ensures Data Freshness: By regularly synchronizing data, the app ensures that users have the most up-to-date information, crucial for decision-making and app functionality.
Minimizes Data Loss Risk: Regular sync intervals help to minimize the risk of data loss or inconsistency, particularly important in scenarios where the app frequently transitions between online and offline states.
Optimizes Network Usage: By syncing data periodically, the app makes efficient use of network resources, reducing the need for continuous data transfer while still keeping the data current.
Note
The periodic synchronization strategy in SailPilot demonstrates a thoughtful balance between data freshness, network resource utilization, and user-centric operational design. It ensures that the application remains both reliable and efficient, particularly in environments with variable connectivity.
Token Handling
SailPilot handles token management and refresh operations through the manage_tokens.dart file. This file contains functions crucial for maintaining authenticated sessions and managing token lifecycle.
refreshAccessToken
The refreshAccessToken function is responsible for refreshing the access token when it expires. It performs the following steps:
Retrieves the current token data from secure storage.
Checks if the token has expired and if there is an internet connection.
If necessary, makes an HTTP POST request to the token refresh endpoint.
Upon successful response, stores the new access token and updates the timestamp.
isTokenExpired
The isTokenExpired function checks if the current access token has expired. It compares the token’s timestamp against the current time and determines if it’s older than one day. If the token is expired or if there are any issues with the timestamp, the function returns true, indicating that a token refresh is needed.
These functions ensure that SailPilot maintains a valid session by refreshing tokens proactively when required and reacting to connectivity changes.