Local-First Architecture: CRDTs & Sync Engines

Q: What is local-first architecture?

Local-first architecture is an approach where an application treats the copy of data on the user's own device as a first-class, authoritative replica rather than a disposable cache of server state. Writes commit instantly to local storage so the user sees the result immediately, with no network round trip in the critical path, and the app remains fully functional offline for both reading and writing. Changes then sync to other devices and to the cloud in the background, using a conflict-free replicated data type to merge concurrent edits automatically. This differs fundamentally from the classic server-authoritative model, where the server holds the only true copy of data and every write must reach it before it is considered durable, and it differs from simple optimistic UI, which guesses at the result locally but still treats the server as the source of truth and can revert the guess. The term and its modern articulation come from the 2019 Ink and Switch essay "Local-first software," and the pattern has matured significantly since, with production systems like Linear's ticket tracker demonstrating it at scale.

Q: What is a CRDT and why does it matter for local-first apps?

A CRDT, or Conflict-free Replicated Data Type, is a data structure specifically designed so that when multiple replicas are edited independently and concurrently, merging their changes always produces the same final result on every replica, with no central server needed to arbitrate conflicts. This matters enormously for local-first apps because once you allow writes to happen locally on multiple devices while offline, you inevitably get concurrent, independent edits to the same document, and you need a principled way to merge them back together when the devices reconnect. Without a CRDT, developers typically fall back to ad hoc strategies like last-write-wins, which silently discards one user's changes whenever two edits conflict, or manual conflict resolution dialogs, which are intrusive and error-prone. A CRDT instead guarantees mathematically that merging is commutative, associative, and idempotent, meaning the order in which changes are applied or re-applied does not affect the outcome, so any two replicas that have seen the same set of operations always converge to an identical state. This is what makes true offline collaboration possible without a central lock or a human resolving conflicts by hand.

Q: What is the difference between a CRDT and optimistic UI?

Optimistic UI and CRDT-based local-first architecture both aim to make an application feel instantly responsive, but they differ in where the authoritative copy of the data actually lives and what happens on conflict. Optimistic UI updates the interface immediately with a guessed result as soon as the user acts, while the actual write is still sent to the server in the background; if the server rejects the write or a conflict is detected, the UI has to revert or reconcile, which users experience as content flickering or disappearing. The server remains the single source of truth throughout. A CRDT-based local-first system instead makes the local copy genuinely authoritative: the write is not a guess awaiting server confirmation, it is a real, permanent local write that is merged with other replicas' writes through the CRDT's deterministic merge algorithm, so there is no reversion because there is no single source of truth to contradict the local state. Optimistic UI reduces perceived latency for a system that is still fundamentally server-authoritative, while local-first with CRDTs changes which copy is authoritative and enables genuine offline operation with real collaborative merging, not just a smoother loading experience.

Q: What is a sync engine and what does it actually do?

A sync engine is the background component in a local-first architecture responsible for exchanging changes between a device's local replica and other replicas, whether those are other users' devices or a cloud relay, without ever blocking the user interface on that exchange. Concretely, it watches the local CRDT document for new operations, sends them to peers or to a server when connectivity is available, receives operations that originated elsewhere, and feeds them into the local CRDT so they merge into the local state. Because this all happens asynchronously in the background, the user's local writes remain instant regardless of network conditions, and the sync engine simply catches up whenever a connection exists, which could be continuously in a well-connected scenario or in occasional bursts if the device was offline for hours or days. The sync engine typically also handles practical concerns such as batching operations for efficiency, retrying failed transmissions, and sometimes compressing the operation log. It is the piece of infrastructure that turns a merely offline-capable app, which just works alone, into a genuinely collaborative local-first app, where multiple people or devices converge on a shared, consistent state.

Q: Does the cloud still matter in a local-first architecture?

Yes, the cloud remains important in a local-first architecture, but its role changes from being the single authoritative store that gates every operation to providing three specific supporting functions. First, durability: if every device holding a replica of a document were lost or destroyed simultaneously, a cloud relay that has also received and stored the operation log serves as a backup so the data is not gone forever, which is a real risk local-first designs must account for. Second, discovery and delivery: when a new device joins, or a collaborator who was never previously connected to a peer needs the document, a cloud service is typically what allows them to find and pull the current state and the ongoing stream of changes, since peer-to-peer discovery alone is often impractical at application scale. Third, authorization and access control: deciding who is allowed to read or write a given document is naturally enforced at a point where you can verify identity, which is usually a cloud-hosted service rather than something enforced purely on-device. So local-first shifts the cloud from a gatekeeper on the critical path of every interaction to a supporting service for backup, discovery, and permissions, which is a smaller but still essential role.

Q: How does local-first architecture relate to on-device and hybrid AI models?

Local-first architecture and hybrid AI models share the same underlying motivation, which is that not every operation needs to leave the device and cross the network before the user gets a useful result, and the two patterns compose naturally in an application that includes AI features. In a hybrid AI setup, a small, efficient model runs directly on the device and handles the majority of routine requests, such as autocomplete, simple classification, or straightforward question answering, with low latency and full offline availability, while a larger, more capable cloud-hosted model is reserved for requests that genuinely need frontier-level reasoning or knowledge the small model lacks. This mirrors the local-first data pattern exactly: the default path is local and instant, and the cloud is invoked selectively rather than on every single interaction. For an application built local-first, wiring AI features to follow the same split keeps the whole experience consistent, so a user working offline on a flight can still get useful AI assistance from the on-device model, and the app does not develop an awkward inconsistency where the data layer works offline but the AI features silently fail without connectivity.

Q: What are the biggest engineering costs of going local-first?

Local-first architecture is not free, and teams should weigh three concrete costs before adopting it. The first is the sync protocol and CRDT selection itself: rather than relying on a database's built-in transactional consistency, the team now owns the correctness of a distributed merge algorithm, which for anything beyond a well-tested library like Automerge or Yjs can involve subtle bugs that only surface under specific concurrent-editing patterns. The second is metadata and storage overhead: CRDTs typically retain tombstones for deleted content and per-operation identifiers to make merging deterministic, and without periodic compaction this metadata can grow unbounded and noticeably bloat storage and slow down merge operations over the life of a long-lived document. The third is testing complexity: verifying that concurrent edits from multiple offline devices merge correctly requires deliberately constructing and testing conflict scenarios that a server-authoritative system with a single write path never has to consider. None of these costs are prohibitive for mature libraries and well-scoped data models, but they are real, ongoing engineering investments that should be weighed against how much the product genuinely benefits from offline capability and instant local response.

Q: When should I NOT use local-first architecture?

Local-first is a poor fit in at least three situations. First, when the application has no meaningful offline use case and users are effectively always connected, such as an internal admin dashboard or an operations console used only in an office with reliable internet, the added complexity of a sync engine and CRDT buys little practical benefit over a conventional server-authoritative design. Second, when the data model requires strict invariants that cannot be expressed as a conflict-free merge, such as double-entry accounting ledgers or inventory counts that must never legitimately go negative, because CRDTs are designed to always converge without a central arbiter, which is fundamentally in tension with enforcing global constraints that depend on the true, current server-side total. Third, when the team does not have the capacity or expertise to own a sync engine and CRDT-based conflict resolution long-term, since these are genuinely more complex than typical server-side transactional logic and under-resourced implementations tend to produce subtle data-loss or divergence bugs that are hard to diagnose. In these situations a well-built server-authoritative or optimistic-UI system, possibly with a lightweight offline read cache, is usually the more appropriate and maintainable choice.