InternalArchitecture
RippleDB Architecture
The end-to-end mental model for the RippleDB library (local-first replication + deterministic reads).
This section is the “base doc”, split into focused pages so it’s easier to read and keep up to date.
If you want the canonical decision log, see the ADRs.
Start here
Purpose & Scope
What RippleDB is, what it is not, and the deliberate non-goals.
Package Structure
Monorepo layering, naming (store-* vs db-*), and dependency graph rules.
→
Core Principles
Local truth, log-based replication, deterministic conflict resolution, explicit reactivity.
→
Core Data Model
Change primitive, HLC, field-level LWW, and tombstones.
→
Sync Model
Append-only history, outbox, cursor pulls, and pull→apply→push.
→
Query Model
Row vs list queries, broad invalidation, sorting/filtering semantics.
→
Performance
Batch reads per tick/RAF to avoid N+1 without join reactivity.
→
UI Integration
DbEvents, list registry, and optional cache invalidation wiring.
→
Comparisons & Out-of-Scope
TinyBase comparison and why CRDT/rich-text stays outside core.
→
Canonical mental model
Local storage is truth
Replication is log-based
Conflicts resolve per field
Row queries are precise
List queries are rerun
Sorting requires rerun
Performance comes from batching
Reactivity is explicit
Magic is avoided