AngoraTek FR
← Back to Blog
Tutorials 9 min read

'It Works in the Elevator' Is a Product Requirement

A field inspector opens your app in a parking garage, two floors of concrete between her and the nearest tower. The form is there. The record the form should have loaded is not, because the connection dropped while the list was still draining, and the spinner has been spinning since the ramp. She does what users do. She drives to the surface, does the job on paper, and the product that just lost that inspection to a clipboard is the same one that passed every test in your office.

The claim of this post: offline is an environment, not an error state, and it deserves design work rather than a retry with better backoff. The app that works in the garage is built in four moves, and the order is not negotiable. Carry the working set onto the device before it is needed. Route every write through a queue that outlives a crash. Replay that queue with the server's revision in hand, never the device's clock. And write the conflict rule before the first conflict, because a merge policy invented during the first merge is invented by whoever filed the angriest ticket.

One worked example carries the whole post, and it is invented on purpose, so that nobody has to argue from a sample size of one client: a road district tracks 4,312 culverts along 620 km of road, and two inspectors write up their condition after storms. The district is small enough that the entire working set rides in a SQLite file on the phone with room to spare, and large enough that sync bugs can hide between drains. Everything below runs against this little world, one culvert and two devices included.

A working set, pulled before the ramp

Move one exists because a write with no base cannot be merged later: whatever the app lets the inspector change has to have been loaded somewhere, or the edit has nothing to be compared against. So the district comes to the device, all of it. 4,312 rows of culvert records, their notes, and a tile bundle of the roads, kept swappable the way we keep every tile source, because a map provider that times out is one more thing that does not come back when you call it. The total is a few megabytes of SQLite, which is why the whole thing rides along without a fight.

The pull happens on the office Wi-Fi at shift start, and the stamp that says when is printed on the screen, culvert list and all. Each record carries the server revision it was loaded at, a small field doing the load-bearing work of the entire design, because move three consumes it. Freshness gets a price tag and the design posts the tag instead of hiding it: a culvert installed after this morning's pull does not exist until the next pull, and the inspector sees the pull date every time she opens the list. That honesty costs one line of interface and prevents the worse failure, which is a confident app implying it has the whole world in its pocket.

Every write goes to an outbox first

Move two is the discipline that survives a dead battery. A write never goes straight at the network; it lands in an outbox table on the device, with the record's key, the intended change, and the base revision the edit was made against. The queue is the product's memory of intention: a culvert marked "barrel crushed" in the tunnel is recorded at the moment of observation, whether or not a single packet leaves the garage.

create table outbox (
  id integer primary key,
  device_id text not null,
  record_id text not null,
  base_revision text not null,
  payload text not null,
  created_at text not null
);

This shape exists because of what the first version revealed. That version posted edits straight at the API whenever a signal bar appeared, and it lost the edit the moment the process died mid-flight under the underpass: the request died, the observation died with it, and the record on the phone looked untouched. An intention that cannot outlive the process that formed it was never recorded. The outbox, by contrast, does not care when the network comes back. That is its virtue, and it is also the source of the problem move three has to solve.

Replay is a conversation about revisions

Replaying an outbox is not uploading. Each entry goes to the server with its payload and its base revision, and the server answers one of three ways. The revision still matches: the edit applies, and the entry leaves the queue. The record moved on while the phone was in the tunnel: that is a conflict, and move four owns it. The request is a retry after a timeout that never actually died: the server dedupes on the device id and the outbox id, so the same observation cannot apply twice.

The device clock appears in none of these decisions, except on the screen. A phone that spent nine days out of coverage is wrong about what day it is in ways nobody can audit later, and we watched the cost of trusting endpoints' clocks in real-time fleet tracking, where ten thousand devices report on their own schedule and the server is the only referee. Here the server stamps authority time; the device stamps what it shows the user. A queue of intentions plus a base revision per entry turns "sync" from an event into a set of small, answered questions, and that reframing is most of the engineering.

Write the conflict rule before the first conflict

Move four is the product decision, and it is the one teams skip. Two inspectors cover the same storm. Inspector A marks the culvert on Miller Road "barrel crushed, debris packed" and adds three lines of notes, from inside the garage, offline. Inspector B, whose device synced at the yard at noon, marks the same culvert "debris partial" and adds her own note. A's replay lands at 4 p.m. against a record that B's replay moved at 12:05. What your product does next is the feature. Every choice here is a policy, and the only failure is pretending there is no policy.

merge(old, ours, theirs):
  for each field:
    ours_changed = ours[field] != old[field]
    theirs_changed = theirs[field] != old[field]
    if ours_changed and not theirs_changed: keep ours[field]
    if theirs_changed and not ours_changed: keep theirs[field]
    if neither changed: keep old[field]
    if both changed identically: keep either
    if both changed differently: send the pair to review
  records with an empty review list apply on their own
  everything else waits in the review queue, whole record

The rule this example installs is field-level, three-way, with a person at the end. One side changed a field and the other did not: that side wins, including the side still in the garage. Both sides changed it to the same thing: nobody argues with an agreement. Both sides changed it differently: the record enters a review queue, where the two values ship side by side with the two notes, and a named human picks or combines. Free text never auto-merges, for one reason: a rule that picks a winner for a field note is a rule that deletes somebody's observation without reading it. Numbers and statuses get the fast automatic path. Words stay with people.

The sync code is plumbing. The review screen, where the two texts sit next to each other, is the product.

Two designs we retired

The first retirement is last-write-wins on the whole record. It is the cheapest thing to ship, and it erases work: inspector B's full-record upload, timestamped after A's, overwrote three lines of field notes A wrote from inside the garage, and the deletion looked exactly like nothing, because the record still had every field filled. The conflict rule above exists because of that failure, not in front of it.

The second retirement is ordering by the device clock. Two phones that spent different amounts of time out of coverage disagree about the order of events by minutes or days, and an audit trail built on their clocks is a story, not a log. Server time, one clock, boring and defensible. The device clock appears on the screen and nowhere near a decision, a display format rather than a judgment.

What this design still gets wrong

The review queue can grow. Two inspectors working through the same storm with a week of no coverage leaves a pile of paired texts waiting for a human, and nothing in the merge machinery shrinks it. The design's honest answer is that some conflicts are judgment calls, and the queue is where they go to be judged, which makes the queue a staffing promise, not a technical one. Deletes are their own limit: a deletion racing an edit in the same window does not auto-resolve here, it reviews, because "the structure is gone" versus "the structure is fixed" is precisely the decision that deserves a person. Photos stay humble too: they upload when the network allows, they queue behind the text, and a record whose photo is pending says so on its face.

None of this makes the garage a guarantee. It makes the garage a place where the product degrades on purpose, to a level it announced in advance: a list stamped with its pull date, a queue that accepts everything, and a review line for the few edits two humans genuinely fought over.

If you take one decision out of this post, take the order. Working set first, outbox second, revisions on replay, conflict rule on paper before the first conflict. Each move exists because of what the previous one revealed, and the whole sequence fits an iteration, not a quarter. The app that passes the elevator test decided, before launch, what happens when two people and one culvert disagree, and the retry library had nothing to do with it.

AngoraTek builds field-data applications that keep working on the far side of a tunnel, and we argue about conflict rules the way this post does. If your product has a garage of its own, bring us the record that got away and we will draw the four moves over your data.

Thanks for reading this far. If this sounds like the problem you're wrestling with, tell us about it. The team reads every message.

Start a conversation