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-0007: List Queries Use Broad Invalidation and Rerun

List queries rerun broadly on dependent entity changes for correctness and simplicity.

Status

Accepted

Context

List queries may contain:

WHERE clauses
ORDER BY clauses
JOINs
aggregates
pagination

Without parsing SQL or re-implementing query logic in JS, it is impossible to determine whether a change affects list membership or ordering.

Decision

RippleDB always invalidates and reruns list queries broadly when dependent entities change.

Precision is intentionally sacrificed for correctness and simplicity.

Alternatives Considered

SQL AST parsing
Query DSL with JS evaluation
Incremental view maintenance
In-memory reactive joins

Consequences

Lists are always correct
Some refetches are unnecessary but safe
Complexity is dramatically reduced
Performance relies on DB efficiency and batching

ADR-0006: Row Queries Are Invalidated Precisely by ID

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

ADR-0008: Sorting Requires the Same Invalidation Strategy as Filtering

Any change to fields used for sorting invalidates and reruns list queries.

On this page

Alternatives Considered