Mobile system design, from a packet to an app · Puzzle 8 · 9 of 11
The database is the truth
The user opens your notes app in a tunnel: a spinner, then an error. On the next screen, a note they just wrote is missing. Both have one cause. Here's the structure Android recommends instead: one place every screen reads from.
The problem
Your notes screen calls the API and shows the result. In a tunnel, it shows a spinner, then an error. Worse: another screen keeps its own list, so a note just written on one screen is missing on the other until a refresh. What structure fixes both?
See it
Both screens observe the local database, the source of truth. They never read the network directly.
Step 1 of 4The repository fetches from the server and writes the results into the database. The screens update from there.
Step 2 of 4The user writes a note in a tunnel. Predict: where does it go, and who sees it?
Step 3 of 4Into the database first: both screens show it at once. The repository syncs it when there's a connection. That's offline-first.
Step 4 of 4
The building block
The problem is that the screen has several places to get data from: the network response, its own list, maybe a cache. When they disagree, the screens disagree.
An offline-first app picks one: the local database (Room, on Android) is the source of truth. (Puzzle 7's HTTP cache still has a job: it makes the repository's network calls cheap. But screens never read it directly.) It's the only place the UI ever reads from.
The parts:
- The repository combines two data sources: the local database and the network API.
- Reads: the UI observes the database, for example as a
Flow. When the database changes, every screen showing that data updates by itself. - Network results never go straight to the screen: the repository writes them into the database, and the screens update from there.
- Writes: the user's change goes into the database first, so it shows at once, even offline, and is marked to sync. When there's a connection, the repository sends it to the server; WorkManager can make sure it eventually does.
In a tunnel, the screen shows what's in the database, with no spinner. The new note shows on every screen at once, because they all read the same table.
Two devices can still edit the same note offline. Then the server must decide who wins; a common rule is "last write wins", by timestamp. It's simple but lossy: the other edit silently disappears, and phone clocks can be wrong, so prefer server time or version numbers. Module 2 covers conflicts.
The analogy
A team with one shared whiteboard. Everyone reads the whiteboard, never each other's notes. The runner who goes to head office (the network) copies what they bring back onto the whiteboard, and takes the whiteboard's new items with them on the next trip.
Check yourself
Sources
- Android Developers: Build an offline-first app ("An offline-first app has a minimum of 2 data sources for every repository that utilizes network resources: The local data source, The network data source"; "The local data source is the canonical source of truth for the app. It should be the exclusive source of any data that higher layers of the app read"; "For mobile apps, a common approach is 'last write wins.'")
What you now know
An offline-first app reads only from its local database, which is the source of truth; the UI observes it and updates on its own. A repository writes changes locally first and syncs them with the network when it can; network results are written into the database, never straight to the screen. Then the app works offline, and every screen agrees.
Answer every question above correctly to unlock the next puzzle.
Something wrong or unclear on this page? Tell me: a puzzle that didn't click is a bug in the puzzle.