agentic-dev-template/docs/decisions/adr-004-dual-mode-client.md

ADR-004: Dual-Mode Payload Client (Local + HTTP)

Status: Accepted

Context

Apps need to access Payload CMS data. Payload 3.x offers both Local API (direct) and REST API (HTTP).

Decision

@repo/cms-client supports both modes via createPayloadClient().

Rationale

• Local mode (primary): Direct Payload instance access — no HTTP overhead, full query capabilities (where, sort, limit, depth, page, populate). All server-side apps use this.
• HTTP mode (fallback): REST API for external consumers without access to a Payload process.
• Payload instance is injected at app startup, not imported — keeps cms-client standalone.
• Both modes share the same PayloadClient interface — consumers don't know which mode is active.