> For the complete documentation index, see [llms.txt](https://spice.docs.medtroniclabs.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spice.docs.medtroniclabs.org/user-guide/offline-and-sync.md).

# Working Offline & Sync

## Feature Overview

The app is built to work in places with little or no mobile signal. Everything you need for daily work is stored on your device, so you can register households, record services and make follow-up calls offline. When a connection is available, the app sends your work to the server and downloads new data for your area.

How it works:

* **Stored on the device.** Households, members, assessments, follow-up lists, forms and settings are kept in an encrypted local database on your device. The data cannot be read outside the app.
* **Saved first, sent later.** Each record you save is stored on the device straight away and marked as waiting to upload.
* **Synchronised in the background.** The app uploads waiting records and downloads changes without you having to do anything.
* **Manual sync.** You can also start an upload yourself from the **Offline Sync** screen.

## What you can do offline

| Without a connection                       | Needs a connection                          |
| ------------------------------------------ | ------------------------------------------- |
| Register households and members            | Signing in for the first time on a device   |
| Record assessments and services            | First-time download of your data            |
| Make follow-up calls and record results    | Uploading your work and downloading updates |
| View the dashboard and member history      | Signing in as a different user              |
| Sign in again as the same user (see below) |                                             |

**Signing in without a connection:** if you have used the app on this device before and there is no connection, the app offers to sign you in offline. Confirm the message to continue with offline features. Only the same user who last signed in can do this.

## First-time sync (initial data load)

The first time you sign in on a device, the app downloads the data you need before you can start work.

1. Sign in while connected to the internet.
2. A loading screen shows **Syncing Offline data** with a percentage. The app downloads, in order: your profile, forms and settings, then the households, members, follow-up lists and service history for your assigned villages.
3. When the progress reaches 100%, the home screen opens.

This can take several minutes, depending on how much data is in your area and how fast the connection is. Keep the app open and stay in a place with a stable signal.

If the download fails, the screen shows a **Retry** button. Tap **Retry** to start again.

The app repeats this full download if your assigned villages change. If new villages are added, only the new villages are downloaded.

If a different user signs in on a device that still holds unsent records from the previous user, the app first uploads those records, then loads the new user's data.

## Background sync

For community health workers and other community-level users, the app syncs automatically:

* when the app opens;
* after you save a household, member, assessment or follow-up call result.

During a background sync:

1. A notification **Syncing Offline data** appears and the home screen shows that syncing is in progress.
2. The app first checks the result of any earlier upload.
3. It uploads records that are waiting.
4. It checks that the server has processed them.
5. It downloads changes made by other users and your supervisors, such as new follow-ups.

Background sync only runs when the device has a connection. If there is none, it starts when the connection returns, and your records stay safely on the device until then.

## The Offline Sync screen

Use this screen to see what is waiting to upload and to start an upload yourself.

1. Open the side menu and tap **OFFLINE SYNC**.
2. Check **Last Synced At** for the time of the last successful sync. It shows `--` if the device has never synced.
3. Check the counts for **Households**, **Household Members**, **Assessments** and **Follow-up**. Each shows how many records are waiting to upload.
4. Tap **Start** when asked **Start offline sync now?**. Tap **Cancel** to leave the screen.
5. Wait while the progress bar runs. Do not close the app.
6. When the upload finishes, tap **OKAY**.

> **Note:** If a background sync is already running, the app tells you **Background sync currently in progress. Please try again later.** Wait for it to finish, then try again.

> **Note:** The progress bar is an estimate. It moves steadily while the app waits for the server to confirm your records, so it may reach a high percentage before the sync is actually finished.

> **Note:** The **OFFLINE SYNC** menu item is shown to community health workers and facility-based community clinicians only.

## Sync status and what the messages mean

| What you see                                                 | Meaning                                                                                                                                   |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Records counted under a heading on the Offline Sync screen   | Saved on the device and waiting to upload.                                                                                                |
| **Your offline data sync has successfully completed!**       | The server has processed your records.                                                                                                    |
| **Failed to sync offline data now. Please try again later!** | The app could not finish the sync, for example because the server did not confirm your records in time. Your data is still on the device. |
| **Network Not Available**                                    | There is no internet connection. Check your signal or Wi-Fi and try again.                                                                |
| **Retry** button                                             | Appears after a connection problem while checking the result. Tap it once you are connected again.                                        |

After you upload, the server takes some time to process the records, so the app checks the result repeatedly for around ten minutes before it gives up.

## If something goes wrong

Records are never deleted from the device because a sync failed. If an upload is interrupted, for example because the connection dropped or the phone ran out of battery, the records are marked for retry and are sent in the next sync.

The app sends each record with a unique reference, so a record that is sent twice is not duplicated on the server.

## Troubleshooting

**Sync is slow**

* Move to a place with a stronger signal and try again.
* The first download and large uploads take longer. Leave the app open and wait.
* Keep the phone charged and avoid running many other apps at once.

**Sync seems stuck on the progress screen**

* Wait for at least ten minutes. The server checks your records in batches.
* Make sure the phone still has a connection.
* If it does not finish, go back to the home screen and open **OFFLINE SYNC** later to try again.

**Sync failed**

* Check your internet connection, then open **OFFLINE SYNC** and tap **Start** again, or tap **Retry** if it is shown.
* Check the counts on the Offline Sync screen to see how many records are still waiting.
* If it keeps failing, contact your supervisor or support team. Do not uninstall the app or clear its data, because records that have not been uploaded would be lost.

**The first-time download shows Retry**

* Check your connection and tap **Retry**.
* If it fails repeatedly, ask your supervisor to check that your account and villages are set up correctly.

**Records are missing from my follow-up list or dashboard**

* Open **OFFLINE SYNC** and check **Last Synced At**. If it is old, start a sync while connected.

**The app says the device has low storage**

* Delete unused files, photos or apps. The app cannot save new data when the device storage is full.

## Tips

* Connect and sync regularly, and always before you hand over, replace or reset a device.
* Sync when you are in a place with a good connection.
* Use your own device and account. If another user signs in on your device, your unsent records are uploaded first.
