Offline-First on a Jobsite Is a Product Decision

Offline-first is usually sold as caching, and it is not. It is a decision about what the application can still do when there is no network, and that list is written by the people who understand the work, not by the people who understand the sync library. A jobsite is not a place where connectivity occasionally fails. It is a basement, a steel frame, a site thirty kilometres from the nearest tower — a partition that lasts the whole shift and recurs every day. The engineering follows from accepting that; it does not substitute for it.

Quick Summary

• A jobsite is a permanent partition, so availability has to be chosen deliberately and some guarantees given up on purpose.
• The core deliverable is a list of actions that must succeed with no signal. That list is a product decision made before any sync code.
• Conflicts are not one problem. Each kind of record is either auto-mergeable, append-only, or needs a human — and the classification is the design.
• Photos and video are the real sync cost. Metadata and media belong in separate queues with separate priorities.
• Retrofitting offline behaviour is close to a rewrite, which makes this one of the few decisions genuinely worth making early.

This is the architecture that the field-adoption half of what construction companies build when their platform runs out depends on. A tool that cannot be used where the work happens is not adopted, whatever its feature list says.

Why Is a Jobsite a Partition Rather Than an Outage?

Because the network is absent by default, and the system still has to be useful.

The distributed systems result here is old and exact. Gilbert and Lynch’s 2002 proof of Brewer’s conjecture established that a system cannot simultaneously guarantee consistency and availability when the network partitions. On a jobsite the partition is not hypothetical, so the choice is not whether to give something up — it is what.

Almost always the answer is availability over strict consistency: the contractor must be able to record what they are doing right now, and the system accepts that two devices may briefly hold different versions of the truth. Saying that plainly has a consequence most teams avoid facing. If two people can write at once and both writes must succeed, then the system will produce divergence, and divergence has to be resolved by a rule you chose rather than by whichever request happened to arrive last.

The most instructive version of this is a device CodeBranch built where the network is not required at all. The INL8 controller in a residential IoT ecosystem operates its eight electrical zones from a physical keypad on the wall, with no internet, no app and no configuration — the electrician installs it and it works. Connectivity, when it arrives, adds remote control, scheduling and over-the-air updates. It does not switch the product on.

That is the architectural posture worth copying even in software that has no hardware: the network should add capability, not grant permission.

What Has to Work With No Signal?

The list, and writing it is the actual design session.

It is not “everything”, and pretending otherwise produces a worse product than choosing. Reading a drawing, recording a measurement, photographing a condition, closing out a task, signing a daily log — these are candidates. Approving a change order that affects a contract value, or reading a price that another system owns, usually are not.

Three questions settle each row:

• Can the user act on the result immediately? If the action only matters once someone else sees it, queuing it offline adds risk without adding value.
• Is the data the user needs already on the device? An action that depends on a server-side lookup cannot be made offline by willpower; it needs the lookup pre-synced, which has its own cost.
• What happens if it turns out to be wrong after sync? An offline action that cannot be reversed cheaply is a liability.

Everything that survives those three questions goes in the offline set, and everything in the offline set needs local storage, a queue, a conflict rule and a visible sync state. Everything outside it can be honest about requiring a connection — which users accept, as long as the boundary is predictable.

Which Conflicts Actually Happen in Construction?

Three kinds, and treating them identically is the mistake.

Most construction field data is append-only, which is good news: two crews photographing the same wall produce two photos, not a conflict. The second category is where automatic resolution earns its keep, and it is well-studied — the 2011 INRIA study of conflict-free replicated data types by Shapiro and colleagues sets out structures that converge without coordination, which is exactly the guarantee an offline field app wants.

The third category is small and dangerous. Two people reporting different quantities installed on the same front is not a merge problem; it is a disagreement about reality, and software that resolves it quietly has destroyed information. These records need both versions preserved and a human prompted.

Classifying every entity into one of those three rows is most of the design work. Teams that skip it end up with one global rule — usually last-write-wins — applied to data where it is catastrophic.

How Do You Sync Photos Without Killing the Device?

By refusing to treat them as just more records.

A day of site documentation is a few kilobytes of structured data and several hundred megabytes of media. If both travel in one queue, the structured record — the part that matters to the office today — waits behind a video. Meanwhile the radio stays active on a weak connection, which is the most expensive thing a phone can do to its battery.

The working pattern separates them:

• Metadata syncs first and alone. The daily log, the measurements and the references to media arrive within seconds of signal. The office sees that the work happened.
• Media syncs on its own policy. Deferred to Wi-Fi where the organization allows it, chunked so a dropped connection resumes rather than restarts, and ordered so the photos attached to flagged conditions go before the routine ones.
• The record is usable while media is pending. A report that shows “3 photos uploading” is more useful than one that does not exist yet.

The same discipline shows up on the hardware side of connected field equipment. In the connected-tool app CodeBranch built for a U.S. tool manufacturer, measurements, annotations and media all attach to a space, and the structured measurement data is small and fast while the photo and video attached to the same space are not. Treating them as one payload would make the fast part as slow as the slow part.

What Does Zero-Configuration Buy You?

It removes the step most likely to be skipped.

Setup is where field software dies. A device or an app that requires a technician, a network credential or a configuration pass is one that gets installed incorrectly, or not at all, by whoever is on site that day. The INL8 modules CodeBranch built self-configure: they detect and join the home network on first power-on, register with the cloud, and appear in the control app without any manual setup. There is no configuration step to skip because there is no configuration step.

In a field app the equivalent is a sign-in that survives, a local store that exists before the first sync, and a first run that works at the site rather than requiring an office visit first. The test is simple and worth applying literally: can someone install this in a basement, with no signal, and start working.

When Is Offline-First More Than You Need?

When the work is not actually in the field.

Some construction software is used in a trailer with Wi-Fi, in an office, or on a tablet that returns to a desk every night. For that, offline-first is engineering spent on a condition that does not occur, and a straightforward online application with good error handling is the better build.

The honest boundary is this: offline-first is worth its cost when field users create data, not merely read it, and when the gap between creating it and reaching a connection is measured in hours. Read-only field access is a caching problem with a much smaller budget.

When the answer does point at offline-first, the decision belongs at the start. That is why CodeBranch settles it in the Product Definition phase of software for construction companies, alongside the question of what the field is actually being asked to capture — the two decisions constrain each other, and both get expensive once the first version is in people’s hands.