InternalADRs
ADR-0014: Monorepo Package Structure and Layering
Lock in package boundaries so core stays runtime/UI agnostic while optional layers provide great DX.
Status
Accepted
Context
RippleDB must remain runtime-agnostic and framework-agnostic while still offering great DX through optional adapters and integrations.
We need clear boundaries so that core logic cannot accidentally depend on UI frameworks or specific databases.
Decision
RippleDB will be organized as a monorepo with layered packages:
- Core primitives: types, HLC, merge semantics
- Client replication orchestration: outbox / pull / apply / push logic
- Server replication orchestration: change append + cursor pull interfaces and helpers
- Persistence implementations
- client truth store implementations:
@rippledb/store-* - server persistence implementations:
@rippledb/db-*
- client truth store implementations:
- UI bindings: optional bindings for cache invalidation and reactivity (
@rippledb/bind-*) - Docs / CRDT: separate modules (future)
Alternatives Considered
- Single package with optional imports
- “Batteries included” framework-specific package
- Multiple repos
Consequences
- Clear dependency boundaries
- Easier maintenance and testing
- Users can adopt only what they need
- Slightly more packaging overhead
ADR-0013: Complexity Is Rejected in Favor of Predictability
Prefer simple rerun-based correctness and defer optimizations until proven necessary.
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.