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

Every app that shows data has to decide which copy is authoritative. In a typical cloud app the server holds that copy. 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.

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.

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.

The phrase is easy to over-read. Three limits are worth keeping in mind.

• 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.

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.