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-0016: store-* and db-* Packages Own Backend/Runtime Dependencies

Runtime-specific deps (SQLite, Postgres, etc.) must live outside core/client/server in store-* and db-* packages.

Status

Accepted

Context

Concrete implementations require dependencies (SQLite driver, Postgres client, etc.). We want to avoid pulling these into the core dependency tree.

Decision

All runtime-/backend-specific dependencies live in persistence packages, for example:

@rippledb/store-sqlite
@rippledb/db-postgres

Core/orchestration packages depend only on interfaces, never on implementations:

@rippledb/core, @rippledb/client, @rippledb/server must not depend on any store-* or db-* package.

Alternatives Considered

A single @rippledb/adapters package
Core selecting implementations via optional dependencies

Consequences

Users install only what they need
Dependency tree stays clean
Clear responsibility separation

ADR-0015: Core Package Must Be Pure and Dependency-Minimal

@rippledb/core contains only pure logic/types and must not depend on UI, runtime APIs, or DB drivers.

ADR-0017: UI Integrations Live in bind-* Packages

Cache invalidation wiring is UI-specific; ship it as optional bind-* packages (e.g. bind-tanstack-query).

On this page

Alternatives Considered