agentic-dev/docs/decisions/adr-003-cms-separation.md

ADR-003: CMS Core + CMS Client Separation

Status: Accepted

Context

Payload CMS needs to integrate with clean architecture without creating circular dependencies.

Decision

Three packages: @repo/cms-core (config + collections), @repo/cms-client (standalone typed client), apps/cms (thin shell).

Rationale

• cms-core is testable independently — collections are just config objects
• cms-client is standalone (no internal imports) — prevents circular deps
• apps/cms is almost empty — just boots Next.js with cms-core's config
• Payload instance injected into cms-client, not imported — app startup code wires them

Circular Dependency Prevention

apps/cms → @repo/cms-core → @repo/core/application (hooks)
@repo/core/infrastructure → @repo/cms-client (standalone)

No cycles because cms-client never imports from cms-core or core.