Local-First Note Architecture at Sub-Millisecond Speed
How Fold avoids cloud round-trips by pairing in-memory React state, single-record IndexedDB writes, and BroadcastChannel IPC across open browser tabs.
Open a physical notebook and the page never asks you to verify a session token. It never stalls behind a spinner while a remote server checks whether your subscription allows offline editing. Pen meets paper with zero network latency.
Most modern web apps moved away from that immediacy, treating the browser as a thin client that waits on someone else's database. Fold works from the opposite rule: your device is the primary source of truth, and the network is completely optional.
The latency tax of cloud-first writing
Cloud-first note apps route every keystroke through a fragile chain of debounced HTTP requests, load balancers, auth middleware, database writes, and WebSocket acknowledgments. Even on fast Wi-Fi that pipeline adds visible sync jitter, and on a train or poor connection it triggers conflict modals or read-only lockouts.
When you create or edit a note in a standard cloud-backed workspace, the app has to coordinate four separate hops before your change is truly settled:
- The editor updates optimistic local UI state so typing feels responsive on screen.
- A debounced mutation serializes the document delta and opens an authenticated HTTPS request.
- A load balancer, auth layer, and database cluster validate permissions and commit the row.
- A WebSocket or polling loop pushes an acknowledgment back so the saving indicator settles.
A private writing instrument should operate at the speed of thought, never at the speed of an HTTP round-trip.
Beyond latency, cloud-first defaults force an unnecessary privacy trade-off. If unencrypted drafts pass through remote servers, you are trusting a third party's infrastructure, retention rules, backup pipelines, and future terms of service with your private notes.
Cloud-first versus local-first architecture
Moving canonical state ownership into the browser eliminates network round-trips, authentication gates, and server-side sync bottlenecks. Instead of treating local storage as a temporary cache, Fold makes IndexedDB (fold_db v2) the primary database and uses browser IPC to coordinate open windows without remote servers.
| Architectural Dimension | Cloud-First Notes App | Fold (Local-First Engine) |
|---|---|---|
| Canonical Source of Truth | Remote server database | Browser IndexedDB (fold_db v2) |
| Keystroke Write Latency | 80 to 400 ms network round-trip | Under 1 ms local transaction |
| Account and Auth Requirement | Mandatory email or OAuth gate | None (open /app and write immediately) |
| Offline Editing | Degraded cache or read-only lock | Full capability with 0 network requests |
| Multi-Window Synchronization | Server WebSocket fan-out | Native BroadcastChannel IPC (fold_sync_v2) |
| Data Ownership | Hosted behind API exports | Plain Markdown .zip and JSON vault exports |
Client-side state and atomic persistence
To keep typing instantaneous without risking data loss, Fold separates fast in-memory React state from durable disk commits. Searching with ⌘K, filtering folders, and switching notes run synchronously against plain JavaScript objects in memory, while editor changes schedule debounced single-record put() transactions in IndexedDB.
export async function idbSaveNote(note: Note): Promise<boolean> {
const normalized = normalizeNote(note);
const db = await openDatabase();
if (!db) return false;
return new Promise<boolean>((resolve) => {
const tx = db.transaction("notes", "readwrite");
const store = tx.objectStore("notes");
const req = store.put(normalized);
req.onsuccess = () => resolve(true);
req.onerror = () => resolve(false);
});
}Why single-record upserts matter
Early browser prototypes often store an entire library of notes as one monolithic JSON array inside localStorage. Once a notebook grows past a few hundred entries, every keystroke forces the browser to JSON.stringify the whole collection and block the main thread while writing megabytes synchronously.
By isolating each note as its own record keyed by id inside the notes object store (with secondary indexes on updated and folder), Fold serializes only the single note you are actively editing. Every other note on disk remains untouched.
Multi-window IPC via BroadcastChannel
Local-first does not restrict you to a single browser tab. Fold uses the native BroadcastChannel API on channel fold_sync_v2 so open tabs and installed PWA windows on the same origin exchange typed save, delete, and batch-update events directly in browser memory with zero polling or server traffic.
Whenever one tab commits a note to IndexedDB, deletes an item, or restores a vault backup, it broadcasts a lightweight message stamped with a unique senderId so the originating tab ignores its own echo:
export type SyncMessage =
| { type: "note_saved"; note: Note; senderId: string }
| { type: "note_deleted"; id: string; senderId: string }
| { type: "batch_updated"; senderId: string };
export class SyncEngine {
private channel: BroadcastChannel | null = null;
private senderId = `tab-${Date.now()}-${crypto.randomUUID()}`;
constructor() {
if (typeof window !== "undefined" && "BroadcastChannel" in window) {
this.channel = new BroadcastChannel("fold_sync_v2");
this.channel.onmessage = (event: MessageEvent<SyncMessage>) => {
const msg = event.data;
// Ignore messages emitted by the current window instance
if (!msg || msg.senderId === this.senderId) return;
this.notifyListeners(msg);
};
}
}
}Closing the visibility gap
Broadcast messages travel in real time while tabs stay active, but browsers routinely throttle or freeze background tabs to save battery. Fold pairs BroadcastChannel with a visibilitychange listener: the moment you return to a dormant window, Fold reconciles its in-memory state with IndexedDB so stale tabs never overwrite newer edits from another window.
Quiet autonomy and the seven local-first ideals
In their 2019 paper Local-First Software: You Own Your Data, in spite of the Cloud, researchers at Ink & Switch defined seven ideals for software where users keep ownership of their files. Fold applies the five ideals suited to a single-player notes workspace across storage, offline caching, and open exports:
- No spinners because note selection, search, and editing run against in-memory React state backed by sub-millisecond
IndexedDBtransactions. - Optional networking because once the Service Worker shell (
fold-v2.1) caches/appand static assets, airplane cabins and offline laptops work identically to fiber Wi-Fi. - Long-term readability because notes export as plain CommonMark
.mdfiles with YAML frontmatter that remain readable decades from now. - Privacy by default because Fold requires zero accounts and sends zero sync traffic, keeping drafts off remote servers and out of AI training pipelines.
- Full user ownership because every note can be inspected, duplicated, exported in bulk (
.zipor.json), or permanently deleted inside your browser.
When an app never needs to phone home, entire layers of visual clutter vanish from the screen:
- Zero login walls before your first word
- Zero sync spinners competing for peripheral attention
- Zero telemetry pings leaking document titles or writing cadence
- Instant cold starts powered by cached Service Worker assets
Local-first architecture turns a browser app into a personal writing instrument that opens in silence, responds immediately, and leaves your words strictly under your control.
References and further reading
- Ink & Switch (2019), Local-First Software: You Own Your Data, in spite of the Cloud, by Martin Kleppmann, Adam Wiggins, Peter van Hardenberg, and Mark McGranaghan.
- MDN Web Docs, BroadcastChannel API, on same-origin cross-window messaging without server polling.
Dhairya Darji
@dhairya0707Creator of Fold. Designing quiet, local-first software instruments with mathematical framing, zero telemetry, and durable on-device storage.
Notes without the noise.
Try the local-first IndexedDB workspace right in this browser. No sign-up required.
Open workspaceMore from Field Notes
How to Install Fold as an Offline PWA on Any Device
Step-by-step guide to installing Fold from foldnotes.web.app as a standalone offline PWA on desktop and mobile, plus how cache updates and backups work.
Browser Storage Limits, IndexedDB, and Data Durability
Why localStorage breaks note libraries, how IndexedDB scales structured text, and how Fold pairs persistent storage with Markdown ZIP and JSON backups.