Local-first data

What does "the device is the source of truth" mean?

It means the copy of the data on the user's own device is the primary, authoritative copy. The app reads and writes that copy first, and servers or other devices hold secondary copies that help with sync and backup rather than deciding what the data is.

TL;DR

Treating the device as the source of truth means a change counts once it is saved locally, any server is another replica, and copies on several devices come back together by merging. It does not remove servers, suit rules that need one authority or guard against phone loss, so keep secondary copies and show what has reached other devices.

Learning objectives

After reading this article you will be able to:

  • Explain what changes when the device holds the primary, authoritative copy
  • Describe how CRDTs bring several primary copies back into agreement
  • Identify what "the device is the source of truth" does not imply

Source of truth in cloud and local-first apps

In a typical cloud app the server holds the authoritative copy; in local-first software it is the copy on the device. Every app that shows data has to decide which copy is authoritative. The Ink & Switch essay that named local-first software puts it plainly: in cloud apps the data on the server is the primary, authoritative copy, and a copy on the client is merely a cache subordinate to the server. A change that never reaches the server “didn’t happen.”

Local-first software swaps those roles. The copy on your laptop, tablet or phone is the primary copy. Servers still exist, but they hold secondary copies to help with access from several devices. “The device is the source of truth” is a short way of saying that swap.

Primary copy on the device

When the device holds the primary copy, writes count once saved locally, the network becomes optional, servers become helpers and the data outlives the service. Moving authority onto the device changes how the app behaves day to day.

  • A write is complete when it is saved locally. The app does not wait for a server to confirm before treating the change as real. The essay notes that all operations can be handled by reading and writing files on the local disk, with synchronisation happening in the background.
  • The network becomes optional. Reading and editing do not depend on a connection, so they keep working in a basement, on a plane or in the field.
  • Servers become helpers. In the essay’s words, cloud servers still have their place for discovery, backup and burst compute. Their job is to support the devices, not to decide what the data is.
  • The data outlives the service. If the primary copy is on the device, the user can keep working with it even if the company behind a server stops running it.

Storing the primary copy also means storing it where it is reliable. Android’s storage guidance, for example, advises keeping data an app’s basic functionality depends on in internal storage or a database, because external storage can be removed.

Merging primary copies across devices

Primary copies on several devices come back together by merging, using conflict-free replicated data types. Once a person uses two devices, or shares a document with a colleague, there are several primary copies, and they can change independently. Nothing ranks one above another, so the app needs a way to bring them back together that does not depend on asking a server which copy wins.

That is the job of conflict-free replicated data types (CRDTs). In the paper that formalised them, Shapiro and colleagues describe data types that let each replica accept updates without remote synchronisation, and whose replicas are guaranteed to converge despite any number of failures. Automerge describes its documents as being like a JSON object and a git repository combined: every change adds to the document’s history, and that history plus its rules for conflicts means any two Automerge documents can always be merged.

The essay is open about a cost of this. With no central source of truth, a document can develop a complex version history, and how to show people the way it came to be is, in the essay’s words, an open question.

Device source of truth limits

Making the device the source of truth does not mean there is no server, that every rule can be settled on the device, or that the device is safe from loss. The phrase is easy to over-read. Three limits apply.

  • It does not mean there is no server. The essay says the key difference is not an absence of servers but a change in their responsibilities: they play a supporting role, not the source of truth.
  • It does not suit every rule. Some decisions need one authority, such as two people booking the last seat. Merging both bookings produces a valid document and a broken business rule. The essay itself sets aside banking, e-commerce and similar services as well served by centralised systems. Those parts of an app need an authority to resolve the conflict, even if the rest of the app is local-first.
  • It does not make the device safe from loss. A phone that is the source of truth is also a phone that can be lost or broken. Secondary copies on other devices or a backup server are what protect against that.

Designing around a device source of truth

Save changes on the device first, treat any server as another replica, show what has reached other devices, and route the few decisions that need one authority through it. A few habits follow from taking the idea seriously:

  1. Persist a change on the device before you show it as saved.
  2. Treat the server, if there is one, as another replica that sends and receives changes, not as the place that confirms them.
  3. Show people whether their changes have reached other devices yet, since “saved here” and “seen elsewhere” are different states.
  4. Keep the few decisions that need a single authority separate, and route those through it.

Frequently asked questions

Does the device being the source of truth mean there is no server?

No. A server can still relay changes, keep a backup and help with discovery. The difference is its role. It holds a secondary copy that supports the devices, instead of being the only place where a change counts.

If every device is primary, which copy is right?

After they sync, all of them. Local-first designs store data in structures that merge, so devices that have seen the same changes end up with the same state. Until they sync, each device shows what it knows.

When is a write complete in a local-first app?

When it is saved locally. The app does not wait for a server to confirm before treating the change as real, and synchronisation happens in the background.

What happens to the data if the company behind a local-first app stops running its server?

If the primary copy is on the device, the user can keep working with it even if the company behind a server stops running it.

What protects the data if the device holding the primary copy is lost?

Secondary copies on other devices or a backup server. A phone that is the source of truth is also a phone that can be lost or broken.

Where should an Android app keep the primary copy of its data?

Android's storage guidance advises keeping data an app's basic functionality depends on in internal storage or a database, because external storage can be removed.

Sources

Build it with Offline Protocol

Offline Protocol's replicated documents keep each device's copy on the device and merge edits when peers communicate, while your existing database keeps records outside that shared scope. The shared state guide covers spaces, merge rules and how to test convergence.

Read the shared state guide