Local-First Architecture

How Store keeps your data on the device first and syncs when connectivity is available.

What local-first means

Local-first software writes data to a local database before anything else. There is no mandatory server round-trip for reads or writes. The network is used for replication, not as a primary data path. This gives you instant reads, zero-latency writes, and full offline capability.

Store implements local-first by committing every write to the local adapter first. When you call store.record("notes").put(), the write is recorded locally immediately. Sync then flushes queued operations to configured remotes.

Offline-first by default

Every Store-backed data set works without a network connection. The sync engine maintains a write-ahead queue that accumulates operations while offline. When connectivity returns, the queue drains automatically in order.

import { createStore } from "@cuitty/store/client";

const store = await createStore({
  module: "notes",
  profile: {
    id: "offline",
    name: "Offline",
    local: { adapter: "local.sqlite", path: ".cuitty/store/notes.sqlite" },
    remotes: [],
    routes: [],
    encryption: { atRest: "preferred", remote: "disabled", p2p: "disabled" },
    sync: { mode: "manual" },
  },
  schema: { notes: { class: "record" } },
});

// These work offline — no network needed
const notes = store.record("notes");
await notes.put("note:1", { text: "Draft while offline" });
const note = await notes.get("note:1");

There is no special “offline mode” to enable. Offline operation is the baseline behavior.

Sync-on-connect

When a remote is configured, Store watches for connectivity changes. On reconnect, it performs a three-step sync cycle:

1. Push — local writes queued since the last sync are sent to the remote.
2. Pull — remote writes from other devices are fetched.
3. Merge — conflicts are resolved using the configured strategy (last-write-wins, custom merge function, or manual resolution).

The sync planner batches operations and deduplicates redundant writes to minimize bandwidth.

Why local-first matters

Traditional cloud-first architectures tie application responsiveness to network latency. A slow API means a slow UI. Local-first inverts this: the UI is always fast because reads and writes hit local storage. The network is an optimization for durability and multi-device access, not a prerequisite for function.

This architecture also gives users real ownership of their data. Records exist on the device regardless of server availability, making data portability and export straightforward.