Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(#1095): Update data sync documentation #1243

Merged
merged 14 commits into from
Dec 4, 2023
Merged
36 changes: 32 additions & 4 deletions content/en/apps/concepts/navigation.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,22 @@ Tap the menu icon in the upper right corner of the header to access other pages,

{{< figure src="sync-status.png" link="sync-status.png" class="right col-6 col-lg-4" >}}

Data synchronisation is important for [offline users]({{< relref "apps/concepts/users" >}}). These users keep a copy of the data they have access to on their device. They can work from their device while disconnected from the internet (offline), by reading from and writing to their copy of the data. "Sync" (synchronisation) is when data on the device is made to match the data on the server. Synchronisation consists of uploading all new or altered data from the device to the server, and downloading new or altered data from the server to the device. This latter step may include the download of software updates to the CHT core or CHT app when available.
Data synchronization is important for [offline users]({{< relref "apps/concepts/users" >}}). These users keep a copy of the data they have access to on their device. They can work from their device while disconnected from the internet (offline), by reading from and writing to their copy of the data. Sync” (synchronization) is when data on the device is made to match the data on the server and requires an internet connection. The CHT app monitors the online status and attempts sync accordingly.

At the bottom of the menu is a notification which provides important information about data synchronisation.
#### Replication Types

Synchronization consists of upward replication and downward replication.
- **Upward Replication**: Uploading all new or updated data from the device to the server. It includes a retry mechanism for handling larger data batches, ensuring a robust and reliable upload process.
- **Downward Replication**: Downloading new or updated data from the server to the device. Downward replication may include the download of software updates to the CHT app when available.

The CHT application manages data synchronization across two types of databases:

- **Main Application Database (`medic`)**: The main database that stores the primary data used by the application. It includes contacts, reports, messages, and other critical documents necessary for the core functionality of the application. This database is synchronized continuously to reflect changes to the application, such as new contact creations. Each user stores a subset of the main database which includes only the documents they're allowed to view.
- **User-Metadata Database(`medic-user-{username}-meta`)**: Each user has a dedicated database that stores operational metadata, including [telemetry data]({{< relref "apps/guides/performance/telemetry" >}}) and error messages. Synchronization occurs at predefined intervals to ensure up-to-date monitoring and analysis.

#### Sync Status Notification

At the bottom of the menu is a notification which provides important information about data synchronization.

If the sync status is green and says “All reports synced,” this means you have successfully uploaded the most recent data on your device to the server. It also means that you downloaded the latest data from the server as of the time displayed. Note that there could be more recent data changes on the server, and it doesn't guarantee you are up to date.

Expand All @@ -50,5 +63,20 @@ If the indicator is red, it means you have data changes waiting to be uploaded t
{{< figure src="sync-successful.jpg" link="sync-successful.jpg" >}}
</aside>

Triggering a manual sync by clicking the "Sync now" button will provide feedback at every step of the process through a snackbar appearing on the bottom side of the screen.
It will also allow to retry the sync process in case of failure.
Triggering a manual sync by clicking the "Sync now" button will provide feedback at every step of the process through a snackbar appearing on the bottom side of the screen. This performs upward and downward synchronization of both databases. It will also retry the sync process in case of failure..

#### Synchronization Triggers
- **On Login**: Synchronization is automatically initiated upon successful user login if the app is connected to the internet.
- **Manual**: Clicking the "Sync now" button.
- **Periodic Sync**: The application performs regular checks and attempts to synchronize. The main application database syncs every 5 minutes, while the user metadata database syncs every 30 minutes..
- **On Reload**: Synchronization is automatically initiated when the user reloads the application, refreshes the page, or clicks the reload button in the "Update available" modal.
- **On Connect**: The app also detects when an internet connection becomes available and attempts to sync immediately.

#### Sync Status States
The synchronization process can be in one of the following states:

- **Unknown**: The sync status is not determined yet.
- **Disabled**: Sync is disabled - only applies to online-only users.
- **InProgress**: Synchronization is currently ongoing.
- **Success**: The last sync operation was successful.
- **Required**: There is data pending synchronization.
Loading