Skip to main content

Offline sync FAQ

Use this page when Achal shows the offline pill, encrypted drafts, pending changes, conflicts or locked changes on this device.

Who can do this: signed-in staff using supported clinic screens; offline writes depend on the same online permissions. Where: the header offline indicator and the affected screen, such as patient registration, queue token or clinical document editor.

What does the offline indicator mean?​

The header pill appears only when attention is needed. It can show offline waiting changes, syncing, conflicts/failed changes, auth pause or locked pending changes.

  1. Click the offline indicator in the header.
  2. Read Changes saved on this device.
  3. Check each item status: Waiting to sync, Changed elsewhere or Could not be saved.
  4. Click Sync now after internet returns.
  5. For failed items, use Retry or Discard.

What works offline today?​

The implemented offline paths are limited and deliberate.

  1. Clinical note (autosave) can be queued only for eligible non-sensitive draft clinical documents already opened online.
  2. Walk-in token can be queued; server numbering is assigned when it syncs.
  3. Patient registration can keep an encrypted local draft, but it is not auto-submitted because duplicate checks need a human.
  4. Rx drafts can use an adoption pattern, but finalizing/signing must be online.

Opening a clinical document for the first time while offline is not supported.

Is offline data encrypted?​

Yes. The server issues a per-session secret from /offline/session-key. The browser derives a non-extractable AES-GCM key and stores encrypted drafts and sync queue in IndexedDB.

Important details:

  1. The secret is bound to tenant, user and JWT session issue time.
  2. The IndexedDB database is achal-offline with object store records.
  3. Offline changes expire after 24 hours.
  4. API responses and PHI are not cached by the service worker.

Why is a document not allowed offline?​

POST /offline/eligibility returns offlineAllowed and reasons. Offline persistence is allowed only for non-sensitive DRAFT clinical documents.

Common reasons include:

  1. NOT_A_DRAFT for a final or signed document.
  2. Restricted document.
  3. Restricted patient.
  4. Sensitive specialty such as psychiatry or psychology.
  5. Sensitive template settings.

If the editor says This record is sensitive and is never stored on this device. Keep this page open until you are back online., do not close the tab until you have connectivity.

What should I do when changes are waiting?​

  1. Reconnect internet.
  2. Keep the tab open.
  3. Click the offline indicator.
  4. Click Sync now.
  5. Resolve failed or conflict items shown in the panel.
  6. If the panel says sign-in is needed, login again.

The indicator can say Offline ? N changes waiting, Syncing N changes?, or Sign in again to sync offline changes.

What should I do when offline changes conflict?​

A conflict means someone changed the same record while you were offline. The panel shows Changed elsewhere.

  1. Open Changes saved on this device.
  2. For that item, read the conflict help text.
  3. Click Keep mine if your version should overwrite after rebase.
  4. Click Use server version if the online version is correct.
  5. Click Keep both if you need to compare field by field later.
  6. Open the document and review highlighted offline copy values before signing.

The system never silently last-writes-wins a conflict.

Can I sign or finalize while offline?​

No. Signing and finalizing need a connection.

  1. If you are offline, keep editing the draft only if the offline banner says it is saved on this device.
  2. Reconnect internet.
  3. Click Sync now.
  4. Wait until all pending changes are synced.
  5. Then sign or finalize.

The clinical document service can return OFFLINE_SIGN_BLOCKED or OFFLINE_SYNC_PENDING to stop signing until sync is safe.

Can I use offline mode on a shared computer?​

Avoid it. Offline drafts are encrypted, but they are still on that browser profile until synced, expired or cleared.

  1. Use personal clinic devices where possible.
  2. Do not use offline mode from a cyber cafe, shared family laptop or patient device.
  3. Before leaving, reconnect and sync all changes.
  4. Sign out only after sync is complete.

Signing out or switching workspace deletes changes that have not synced yet.

What happens on logout, tenant switch or session expiry?​

The offline runtime is session-bound.

  1. Logout wipes records and queue.
  2. Tenant switch wipes records and queue.
  3. Boot without a valid session wipes leftovers.
  4. Same user re-login after session expiry can re-key records if the old key is still in memory.
  5. Reload while offline keeps the store locked until the app can fetch a new session key.

If you see N offline changes locked ? reconnect to sync, reconnect before closing the browser.

How do I install the PWA for better offline use?​

The app has an installable PWA shell in production.

  1. Open Achal in Chrome or Edge on the clinic device.
  2. Use the browser Install app or Add to home screen option.
  3. Open the installed app once while online.
  4. Login and open the screens you need before going offline.
  5. When a prompt says A new version of Achal Healthcare is available., click Reload at a safe time.

Installing the PWA does not make every screen work offline; it only improves app loading and update behaviour.

What if browser storage is full or IndexedDB is unavailable?​

When IndexedDB or WebCrypto is unavailable, the app keeps working online-only or falls back to in-memory storage for that tab. In-memory drafts disappear when the tab closes.

  1. Reconnect internet and sync immediately.
  2. Do not close the tab until Everything is synced.
  3. Free space on the device.
  4. Avoid private/incognito mode for clinic work.
  5. If the same item keeps showing Could not be saved, copy the visible non-PHI error code and contact support.

Still stuck?​

Open Help & Support (/app/support) and send the screen name, item type, time, offline indicator text, any error code, and a screenshot with patient details hidden. Never paste patient clinical data into support chat.