ADR-028: Direct Replication Is the Only Sync Path

Status: Accepted Date: 2026-10-13

Context

forked is local-first: PouchDB in the browser is the working copy, and CouchDB is the optional central store. A proxy that forwards replication traffic through a custom backend would add a permanent service, a second code path, and a single point of failure for sync.

Decision

1. The PWA replicates directly with CouchDB. No backend proxies sync traffic.
2. CouchDB is the only required backend component for shared storage. Any custom backend is limited to handing out credentials (ADR-038); it is never in the data path.
3. Devices authenticate with a CouchDB user (self-hosted mode, Basic auth) or with a short-lived CouchDB token from an operator gateway (forked cloud mode); the deployment selects the mode (ADR-038).
4. Conflicts follow ADR-025.

Consequences

• One sync path to build, test, document, and secure; the app works offline and syncs whenever CouchDB is reachable.
• Every deployment must expose CouchDB to browsers through a reverse proxy with TLS and CORS.
• No sync payload end-to-end encryption.