Getting Started

Guides

Adapters

Reference

Internal

RippleDB Architecture Purpose & Scope Package Structure & Dependency Rules Core Principles Core Data Model Sync Model Query Model & Invalidation Performance via Batching UI Integration (Optional)Comparisons & Out-of-Scope

Architecture Decision Records (ADRs)ADR-0001: Local Storage Is the Source of Truth ADR-0002: Replication Is Log-Based (Append-Only), Not State-Based ADR-0003: Field-Level LWW Using Hybrid Logical Clocks (HLC)ADR-0004: Deletes Are Modeled as Tombstones ADR-0005: Distinguish Row Queries from List Queries ADR-0006: Row Queries Are Invalidated Precisely by ID ADR-0007: List Queries Use Broad Invalidation and Rerun ADR-0008: Sorting Requires the Same Invalidation Strategy as Filtering ADR-0009: Performance Is Achieved via Batched Reads, Not Join-Based Reactivity ADR-0010: UI Cache Integration Is Optional and Decoupled ADR-0011: List Query Dependency Mapping Is Explicit (Registry-Based)ADR-0012: CRDTs Are Explicitly Out of Core Scope ADR-0013: Complexity Is Rejected in Favor of Predictability

Packages

ADR-0014: Monorepo Package Structure and Layering ADR-0015: Core Package Must Be Pure and Dependency-Minimal ADR-0016: store-* and db-* Packages Own Backend/Runtime Dependencies ADR-0017: UI Integrations Live in bind-* Packages ADR-0018: Package Names and Intended Responsibilities ADR-0019: Strict Dependency Graph Between Packages

InternalADRs

ADR-0005: Distinguish Row Queries from List Queries

Row queries and list queries have fundamentally different invalidation semantics.

Status

Accepted

Context

Different query types have fundamentally different invalidation semantics.

Treating all queries uniformly leads to either stale data or excessive invalidation complexity.

Decision

RippleDB explicitly distinguishes:

Row queries (fetch by primary key)
List queries (WHERE, ORDER BY, JOIN, aggregates, pagination)

Each category has its own invalidation strategy.

Alternatives Considered

Uniform query treatment
Automatic dependency graph inference
Reactive joins

Consequences

Invalidation logic becomes simpler
Developers must classify queries correctly
Enables predictable correctness guarantees

ADR-0004: Deletes Are Modeled as Tombstones

Deletes are conflict-resolvable fields (deleted + deleted_tag) rather than hard row removal.

ADR-0006: Row Queries Are Invalidated Precisely by ID

Row queries invalidate by primary key; list queries use broader invalidation.

On this page

Alternatives Considered