Engineering/ Company
Offline-first documents: epochs, checkpoints and encrypted vaults
The hardest part of offline editing isn’t storing the file. It’s deciding, safely, what happens when you come back online.
The editor goes on the device
Our collaborative editor normally runs against a live room on the server. For offline work we bundle the same editor into the desktop and mobile apps and serve it locally, so a document opens identically with or without a connection.
The vault
Offline copies live in a per-user vault encrypted with AES-256-GCM. The key is held in the operating system’s keychain or keystore, and each blob is bound, through authenticated data, to the user, the document and the slot it belongs to, so a copy can’t be swapped between users or documents. The vault keeps recent and pinned documents, locks after 30 days without a check-in, and is erased on sign-out or loss of access.
Epochs: knowing when not to merge
Every live room has a lineage epoch that rotates whenever the document is reset (for example, when a version is restored). Offline edits remember the epoch they started from. On reconnect, if the epoch still matches, we take a checkpoint and merge; the merge is recorded with who, when and which device, and can be undone from the checkpoint. If the epoch has moved on, merging would mix two different documents, so we save the offline work as a copy beside the original instead.
Lessons
- Never let a clean cache overwrite unsynced state
- Seeding an offline room from the file is not an edit
- Replay queued updates only after the room is fully synced
