Skip to content
Pyxis CMS Docs

Shadow Content (Drafting System)

Pyxis CMS uses a Shadow Content architecture. This pattern allows editors to work on new versions of a page without affecting the live site until they are ready to publish.

The Core Concept

Section titled “The Core Concept”

Unlike traditional CMS systems that might overwrite content immediately or use a complex versioning table, Pyxis uses a dual-column approach within the same record. This ensures data integrity while keeping the API logic simple and performant.

Data Structure

Section titled “Data Structure”

Every page record in the database contains two primary JSONB columns:

  • content_draft: The “Shadow” column. This is where all active editing happens. Every time an editor clicks “Save”, the data is stored here.
  • content: The “Public” column. This is the source of truth for the live website.

The Workflow

Section titled “The Workflow”
  1. Creation: When a page is created, both columns are initialized (usually as empty arrays).
  2. Editing: As the editor adds blocks or changes text, only the content_draft is updated.
  3. Previewing: The editor can view the current state of content_draft on the frontend using a secure Preview Token.
  4. Publishing: When the “Publish” button is clicked, the system performs an atomic update, copying the entire value of content_draft into content.

API Resolution Logic

Section titled “API Resolution Logic”

The Pyxis API is “Context Aware.” It decides which column to serve based on the request headers:

  • Standard Request: Returns the content column. If the page is not published or is private, it returns a 404 error.
  • Preview Request: If a valid X-Pyxis-Preview header is present, the API bypasses visibility checks and returns data from content_draft.

⚠️ IMPORTANT: This separation ensures that even if a developer makes a mistake in the frontend logic, the draft content is never exposed to the public because the Laravel backend strictly guards the content_draft column.

Benefits

Section titled “Benefits”
  • Zero-Downtime Updates: Publishing is a simple database update operation.
  • Editor Safety: Editors can experiment with complex block layouts without the fear of breaking the live site.
  • Simple Rollbacks: Since the previous live version stays in content until the very last moment, the system is extremely stable.