CRDT Sync Overview

NodeDB bridges AP (available, partition-tolerant) on edge devices with CP (consistent, partition-tolerant) in the cloud.

How It Works

1. Device writes locally — Available immediately, no network required
2. CRDT delta produced — Each write generates a Loro CRDT delta
3. Connectivity returns — Deltas sync to Origin via WebSocket (port 9090)
4. Origin validates — SQL constraints (UNIQUE, FK, CHECK) checked at Raft commit
5. Committed — Delta replicated via Raft, broadcast to connected clients
6. Conflict — Failed constraints produce a typed CompensationHint back to device

Shape Subscriptions

Devices subscribe to a subset of data — not the entire database:

SUBSCRIBE SHAPE ON users WHERE user_id = $me;
SUBSCRIBE SHAPE ON tax_rates WHERE jurisdiction IN ('US-CA', 'US-NY');

Changes within a device's shape are pushed in real time.

Multiple Devices

Multiple devices converge to the same state regardless of operation order. Loro's operation-based CRDTs guarantee eventual consistency without coordination.

Local Engine Capabilities

All eight engines work locally on NodeDB-Lite: document, KV, columnar, timeseries, spatial, vector, array, plus graph traversal and FTS overlays — with sub-millisecond reads and no network dependency.