How we made Notion available offline

Summary

Notion's Offline Mode required turning a best-effort SQLite cache into storage that could guarantee a page and all its dependent records were available without a network connection. The system uses a forest of offline page trees backed by offline_page and offline_action tables, allowing independent reasons such as explicit toggles, favorites, automatic downloads, and inheritance to coexist while preserving hierarchy. To keep content current, clients subscribe to push channels emitted by the page version snapshot system, then use lastDownloadedTimestamp and server lastUpdatedTime to fetch only newer pages after reconnecting. When pages or databases change, the client reconciles fresh page and database snapshots with offline_action, adding or removing rows rather than rebuilding entire trees. This makes offline availability precise and eventually consistent, while supporting conflict resolution through the CRDT data model.

Takeaways

1. 1

   offline_action records each independent reason a page is available offline, so removing one reason does not remove access while another reason remains.

2. 2

   Clients subscribe to per-page update channels and compare lastDownloadedTimestamp with the server's lastUpdatedTime to fetch only pages that changed while offline.

3. 3

   Fresh page and database snapshots are reconciled with offline_action by adding inherited descendants and removing entries for deleted databases or out-of-view rows.