Select a result to preview

Payload CMS Architecture

Document: 15-payload-cms-architecture.md
Version: 1.0.0

Purpose

This document defines the architecture, responsibilities, and implementation standards for Payload CMS within Rundown projects.

Payload CMS is the official content management system used across all Rundown applications. It serves as the central platform for managing structured content while integrating seamlessly with the frontend and supporting services.

This document establishes how Payload should be used, what responsibilities it owns, and how it interacts with the rest of the application architecture.

Payload Philosophy

Payload is the source of truth for all client-managed content.

Content should be authored, validated, and managed within Payload before being consumed by the frontend.

The frontend is responsible for presenting content.

Payload is responsible for managing content.

Responsibilities

Payload owns:

Non-Responsibilities

Payload should not own:

Payload manages data, not presentation.

Collections

Collections represent repeatable content.

Examples include:

Collections should be:

Avoid combining unrelated content into a single collection.

Globals

Globals represent singleton content shared across the application.

Typical globals include:

Globals should only be used when exactly one instance of the content exists.

Blocks

Blocks provide modular content construction.

Examples:

Each Payload block should correspond to a reusable frontend component.

A one-to-one relationship between Payload blocks and React components should be maintained wherever practical.

Fields

Field definitions should:

Fields should model business requirements rather than frontend implementation details.

Relationships

Relationships should be used to avoid duplicated data.

Examples:

Relationships improve consistency and simplify content management.

Media

Payload stores references to media.

Actual media files are stored in Cloudflare R2.

This separation improves scalability and reduces database size.

Access Control

Payload should implement role-based permissions.

Typical roles include:

Each role should receive the minimum permissions required to perform its responsibilities.

Hooks

Hooks should be used to automate predictable content workflows.

Appropriate examples include:

Hooks should remain deterministic and avoid complex business logic.

API Usage

Payload APIs should be treated as the canonical source for managed content.

The frontend should consume Payload through well-defined queries rather than duplicating business rules.

Avoid exposing unnecessary data through public endpoints.

Drafts & Publishing

Projects requiring editorial workflows should use:

Publishing workflows should support non-technical content editors.

Content Modelling Principles

Every content model should be:

Content structures should reflect business concepts rather than page layouts.

For example:

Use:

Instead of:

Business entities remain reusable across multiple pages.

Payload Directory Structure

Standard structure:

payload/

collections/

globals/

blocks/

fields/

hooks/

access/

plugins/

Each directory should have a single responsibility.

Engineering Decision

Content Source of Truth

Status: Accepted

Decision

Payload CMS is the single source of truth for all client-managed content across Rundown applications.

Reasoning

Using Payload as the central content platform:

Payload Checklist

Before implementing a new collection or global, verify:

Summary

Payload CMS serves as the content engine for every Rundown application.

By separating content management from presentation, Payload enables flexible, reusable, and maintainable content structures while providing clients with a powerful yet intuitive editing experience.