InternalADRs
Architecture Decision Records (ADRs)
The canonical set of architectural decisions for RippleDB (with context, alternatives, and consequences).
ADRs are how we keep the architecture coherent over time. Any change that contradicts an existing ADR should add a new ADR that explains why.
Start here
Local Storage Is the Source of Truth
Durable local storage is canonical; UI state is derived from it.
How to use ADRs
- Read in order (0001 → 0013) to build the mental model.
- If you contradict an ADR, write a new ADR explaining why.
- Prefer small ADRs over huge ones.
Core Principles
2 ADRs
Sync & Conflicts
3 ADRs
ADR-0002
Replication Is Log-Based (Append-Only)
Replicas sync via an append-only change log (cursor pull + outbox push).
→
ADR-0003
Field-Level LWW Using Hybrid Logical Clocks (HLC)
Conflicts resolve per-field by HLC tags, not per-row.
→
ADR-0004
Deletes Are Modeled as Tombstones
Deletes participate in LWW to prevent resurrection.
→
Query Model
5 ADRs
ADR-0005
Distinguish Row Queries from List Queries
Row and list queries have different invalidation semantics.
→
ADR-0006
Row Queries Are Invalidated Precisely by ID
Updates invalidate ["entity", id]; deletes invalidate and remove cached rows.
→
ADR-0007
List Queries Use Broad Invalidation and Rerun
Correctness over precision: rerun lists rather than attempt query introspection.
→
ADR-0008
Sorting Uses the Same Invalidation Strategy as Filtering
Sorting can reorder entire lists, so it triggers full reruns like filtering.
→
ADR-0011
List Query Dependency Mapping Is Explicit (Registry-Based)
Optional registry maps list key prefixes to dependent entities for invalidation.
→
Performance
1 ADRs
Packages
6 ADRs
ADR-0014
Monorepo Package Structure and Layering
Layer packages so core stays runtime/UI agnostic while optional layers provide DX.
→
ADR-0015
Core Package Must Be Pure and Dependency-Minimal
@rippledb/core is pure logic/types with no UI/runtime/DB deps.
→
ADR-0016
store-* and db-* Own Runtime Dependencies
Runtime deps (SQLite/Postgres/etc.) live outside core/client/server in store-*/db-*.
→
ADR-0017
UI Integrations Live in bind-* Packages
Cache invalidation wiring is UI-specific; ship as optional bind-* packages.
→
ADR-0018
Package Names and Intended Responsibilities
Canonical naming: store-* (client truth), db-* (server persistence), bind-* (UI).
→
ADR-0019
Strict Dependency Graph Between Packages
Enforce a strict dependency graph to prevent layering erosion.
→
Integration & Product
1 ADRs
Scope & Process
1 ADRs