ADR 0001: Reversible content backendCopy Anchor Link

• Status: superseded by ADR 0003
• Date: 2026-07-18

Historical decision only. Do not use this ADR to justify new Payload, PostgreSQL, or Puck work in EXO. ADR 0003 makes Convex the default authority for EXO-owned state and assigns Page editing and Puck to Construct.

DecisionCopy Anchor Link

Exo will use Payload with PostgreSQL, hosted initially by Neon, as its canonical content system. Neon is an operational provider rather than a domain dependency.

Convex remains an intentional future option. The current choice can be revisited after feedback from the Convex team or once Exo has workloads where Convex's reactive state model materially improves the product.

Why this is not a configuration toggleCopy Anchor Link

Payload currently has official adapters for PostgreSQL, MongoDB, and SQLite. Convex exposes a different execution, query, identity, and realtime model. A full switch therefore requires either a production-grade Payload database adapter or a replacement CMS persistence implementation.

Exo must make that migration controlled and testable, but must not describe it as effortless until those missing components exist.

Portability requirementsCopy Anchor Link

1. Application rendering reads canonical DTOs through ContentRepository.
2. Provider-specific code stays under src/platform/content/<provider> or Payload configuration and migrations.
3. Canonical records use UUIDv7 identifiers. Provider-native identifiers are mapping details.
4. No feature may require raw SQL outside migrations or a provider adapter.
5. Tenant exports use a versioned, newline-delimited JSON format with media manifests and checksums.
6. Imports are idempotent and preserve canonical IDs, timestamps, slugs, relationships, and publication state.
7. Tenant isolation, drafts, versions, access rules, and referential integrity must pass the same contract suite for every backend.
8. A change-data or event interface must be introduced before adding a second live backend; ad hoc dual writes are prohibited.
9. Production cutover requires reconciliation counts, relationship validation, media verification, and a documented rollback window.

Convex activation gatesCopy Anchor Link

A Convex implementation may become canonical only after it supports:

• all ContentRepository behavior;
• Payload-equivalent editorial writes or a replacement admin workflow;
• tenant-scoped authorization on every query and mutation;
• drafts, publishing, versions, redirects, forms, and media references;
• complete export and restore;
• migration rehearsal against a production-shaped tenant;
• operational backup, observability, and incident procedures.

Near-term use of ConvexCopy Anchor Link

Convex may be added earlier as an optional realtime service for presence, deployment progress, preview state, notifications, or activity feeds. Durable CMS records remain in the canonical content backend until the activation gates are met.