ADR-0001: Postgres as Sole Source of Truth
Status: Accepted Date: 2026-08-05
Context
Section titled “Context”The service needs storage for identity, tenancy, flag definitions, and audit logs. D1-per-tenant was considered for domain data (flags, projects) to gain tenant isolation.
Decisions
Section titled “Decisions”All source-of-truth data lives in a single shared Postgres with org_id on every table. D1 and KV are used only for derived, rebuildable data (materialized flag snapshots on the read path).
Consequences
Section titled “Consequences”- One migration toolchain; transactions span mutations + audit
- Cross-tenant queries (metering, admin) remain simple
- Tenant isolation becomes a data-layer seam (TenantStore interface), deferred as an enterprise-tier concern
- D1 corruption/loss on the read path is recoverable by re-materializing from Postgres
Alternatives Considered
Section titled “Alternatives Considered”- D1-per-tenant for domain data: rejected since no cross-DB foreign keys or transactions, two migration toolchains, weak JSONB support for targeting rules, source-of-truth data in a constrained store
- Schema-per-tenant from day one: rejected since operational cost before there are tenants