Skip to Content
Docs

CMS Overview

How Yayaw content surfaces, data models, media, sections, pages, design tokens, and email templates fit together.

Overview

Yayaw's CMS is the content operating layer inside the dashboard. It combines structured data, reusable sections, pages, media assets, public design tokens, transactional email templates, and component recipes under one authorization model.

The main entry point is:

  • /dashboard/content

That dashboard is a screen: a Period filter, key numbers (published pages, pages waiting for publication, page views compared with the previous period, media storage), page views by day and top pages, recently edited pages, a To do list of what needs attention, and charts of media by kind and pages created by month. Every number is read behind can() for the person viewing it, and organization admins can customize the screen (see Dashboard). The section navigation leads to every content surface available to the current user.

Surface Map

SurfaceRoutePurpose
CMS dashboard/dashboard/contentContent screen: key numbers, page views and what needs attention
Pages/dashboard/content/pagesPublic and organization page composition
Documentation/dashboard/content/documentationVersioned bilingual Fumadocs content and navigation
Sections/dashboard/content/sectionsReusable page sections, generated recipes, and form sections
Data models/dashboard/content/data-modelsTyped CMS model definitions
Data entries/dashboard/content/dataPublished singleton and collection content
Media/dashboard/content/mediaOrganization-scoped binary assets and generated images
Components/dashboard/content/componentsUI component registry, previews, and imports
Design tokens/dashboard/content/design-tokensRuntime public-theme token overrides
Email templates/dashboard/content/email-templatesReact Email transactional templates

Content Stack

The CMS is layered deliberately:

  1. Data models define typed fields, localization rules, and cardinality.

  2. Data entries publish shared values such as header menus, footer menus, and site variables.

  3. Media assets provide durable public URLs for selected or generated files.

  4. Components define the reusable UI inventory and recipe renderers.

  5. Sections define reusable page units with neutral example content and editable inputs.

  6. Pages compose layout nodes, component references, and published section references into public or organization-member routes, then fill section inputs through page-level bindings.

  7. Design tokens affect public runtime presentation through global and organization layers. One global page can additionally own a bounded semantic color and sans/serif layer in its immutable revision.

  8. Transactional email templates reuse CMS variables where appropriate but send through the email runtime, not the public page renderer.

Documentation is a dedicated headless CMS surface rather than a Page/Puck channel. Each logical document stores the English and French content in one immutable revision, so publication switches both locales together. The CMS persists its shared path, parent, navigation order, validated Markdown source, safe render tree, table of contents, and search structure. Fumadocs remains the public layout and rendering system for /[locale]/docs/*; only its content source is resolved from the published database entries.

The documentation editor shares the Page editor's compact toolbar, central canvas, and collapsible properties panel. A separate language selector switches localized content without mixing languages with the Visual, Markdown, and Preview modes. Visual editing uses Tiptap, the same engine as the email editor, for headings, text formatting, links, images, lists, code blocks, and GFM tables. Markdown remains the stored source. Specialized MDX widgets and unsupported syntax stay as inert source blocks or inline tokens; edit them in Markdown mode and use Preview to inspect the compiled public rendering. Switching modes alone does not rewrite the source. Saving still creates one bilingual revision and requires a change reason; publication retains server validation and conflict checks.

The documentation Markdown dialect accepts ordinary Markdown, GFM tables and code fences, plus the small allowlist of package-install widgets used by the Yayaw Table guides. Imports, exports, expressions, raw executable MDX, and unknown components are rejected before a draft can be published. Documentation uses the dedicated documentation:list, documentation:read, documentation:manage, and documentation:publish authorization contract. These dashboard permissions are seeded only for the Super Admin role; no organization role receives documentation authoring access.

This split keeps reusable structure in one place while page-specific editorial copy stays on the page instance. Section templates should behave like a catalog or Storybook example: use neutral fixture copy such as Lorem Ipsum in the section itself, then bind final copy, links, JSON lists, and media through PageSection.inputBindings or PageSection.mediaBindings when the section is placed on a page.

Authoring Flow

A typical CMS change follows this path:

  1. Create or update the structured source in data models, data entries, or media.

  2. Build a reusable section when the content should appear on more than one page.

  3. Compose the page in the Puck editor using built-in layout nodes, section references, and direct component references only when needed.

  4. Publish the page or section after validation diagnostics are clean.

  5. Verify the public or organization-member runtime route.

Page width and section rhythm belong to the serialized layout. The public renderer never infers them from /, /table, or any other path. A page draft sets page.layout.bodyWidth, page.layout.sectionGap, and page.layout.sectionFrame; they compile to the root PageStack container, gap, and shared section-frame behavior. sectionFrame: "token" preserves the standard public spacing wrapper, while "none" lets art-directed sections own their boundaries without a second uniform frame. The shared contained layout still reads its maximum width and responsive gutters from the page-container-* public design tokens.

A global public page can set page.designTokens without changing the global token record. The optional versioned payload supports light/dark semantic colors (every light color needs a dark value) and approved loaded sans/serif stacks only. When the field is omitted, the page inherits the global and organization layers. Layout/effect tokens, mono fonts, arbitrary CSS, URLs, and unregistered families are rejected. The normalized layer is stored in the page revision and uses the same scoped wrapper in immutable draft preview and published runtime.

AI-assisted flows follow the same persistence model. Page AI promotes generated content into reusable sections, Page AI image generation persists media through the media library, and missing section publication causes an explicit failure instead of an inline fallback.

MCP-assisted page design follows the same product model, but the connected Codex or ChatGPT client owns the creative reasoning and image generation. Yayaw does not call a server-side text model for this workflow. The MCP provides the art-direction vocabulary, CMS inventory, durable media ingestion, validation, draft persistence, and previews so the client can spend its existing context instead of paying for a second model pass.

MCP page drafting

New pages use three calls:

  1. yayaw_cms_context_get (read) returns, for the requested scope (default organization) and orgId, the art-direction vocabulary (creative composition tokens, page layout options, page design tokens, example recipes, formSection, and catalogProductSection; skip it with includeVocabulary: false), the published sections the page can reuse with their inputs and media slots, the visible component catalog, and up to 50 recent organization images.

  2. yayaw_cms_page_draft (write) creates the draft page in one call: name, optional path, slug, channel, locales, defaultLocale, titleByLocale, seo, layout, designTokens (global public pages only), and 1–24 sections. Each section either creates a new composition section (kind: "create" with a definition) or reuses a published section of the scope (kind: "reuse" with sectionSlug; an organization's own section wins over a shared one with the same slug). Input and media bindings are validated against the section's declared inputs and media slots. New sections are created and published to the section library in the same call; a published section is only a reusable building block, and nothing is public until a page showing it is published. pageSlug with expectedRevisionId adds a new draft revision to an existing page instead. dryRun: true validates without writing. The result returns the page (id, path, slug, revisionId, validationStatus), short-lived signed preview URLs per locale, and the yayaw_pages_publish arguments.

  3. yayaw_pages_publish (publish) validates the exact head revision, its validation status, its bounded dependency set, and page design tokens. Show the previews to the user and get their approval first. A page with a form section is refused; a member publishes it from the dashboard.

yayaw_pages_save_draft saves a whole page document as a new draft revision with optimistic locking on expectedRevisionId. An organization-scoped actor extends its own organization's component catalog with yayaw_component_recipe_import (declarative recipes only), then yayaw_component_publish with the exact returned revisionId.

Private media uploads use a distinct private STORAGE_MEDIA_STAGING_BUCKET when CMS_MEDIA_STAGED_UPLOADS_ENABLED=true. Private grants use the opaque same-origin app proxy and keep S3_ENDPOINT internal by default. Only configure S3_SIGNED_PUBLIC_ENDPOINT when the application host cannot stream the 250 MB media contract; it must be a safe public HTTPS S3 API origin and switches uploads only. Both transports require conditional no-overwrite PUTs. The verified staging object remains private through grant expiry and a 24-hour settlement window so it blocks replay across instances. The reaper repeats deletion during settlement and marks cleanup complete only after its final delete.

Recipe presentation must use Yayaw/shadcn semantic design-token roles. Adjust brand color values through the CMS design-token layer when needed instead of hard-coding page-specific colors into reusable runtime components.

Draft preview URLs are bearer credentials. They expire after a short period, resolve one immutable revision, bypass public runtime caches and analytics, use noindex/nofollow, and are blocked on organization custom domains. Configure CMS_PREVIEW_SIGNING_SECRET as a dedicated high-entropy server secret in production; BETTER_AUTH_SECRET is the fallback signing source.

Signed draft preview routes explicitly run through the request proxy even though their bearer tokens contain a dot. They are not static files: the proxy must forward the route locale and pathname for the document language and shared layouts, and enforce the organization custom-host restriction.

Runtime Resolution

Published content resolves from immutable revisions and publication rows:

  • pages load ui_page_publications and render the published PuckPageDocumentV1

  • section references resolve through ui_section_publications, first by current section ID and then by scoped slug/slug fallback so older page revisions keep rendering after section IDs are repaired

  • page-level PageSection bindings override section fixture props at runtime, so a catalog section can stay generic while each page instance carries the final localized content

  • literal component and section props accept bounded JSON values directly, including nested arrays, objects, and null; recursive valueShape contracts validate nested fields while legacy stringified JSON remains readable

  • data bindings resolve published global or organization CMS data entries

  • media bindings use the stored public URL from media_assets

  • public design tokens resolve from saved global/organization payloads, then an optional global-page revision layer applies inside that page wrapper

  • transactional emails load the active database template for the requested locale before falling back to component defaults

Global public pages feed /sitemap.xml and public SEO metadata. Organization member pages require membership and emit noindex metadata even when page-level SEO fields exist.

Generated sections and creative compositions share the same media optimization allowlist as the Next.js image service. It includes STORAGE_PUBLIC_BASE_URL and the exact retired public media bucket referenced by reviewed Yayaw bootstrap content and existing revisions. This compatibility path does not rewrite stored URLs, migrate media, or permit other Supabase projects, private buckets, or signed endpoints. Existing revisions receive responsive image variants without being republished; unrecognized external sources remain direct images. Only the selected critical image is eager/high-priority, while other CMS images stay lazy-loaded.

Localization

CMS documents use the configured app locales from src/config/i18n.config.ts. Current locales are English and French.

Localized content appears in:

  • page copy and SEO fields

  • global and organization data entry values

  • header and footer menu entries

  • generated section recipe values, including the legal-page legal variant

  • transactional email subjects, preview text, body HTML, and text exports

Generated page section bindings are stored as JSON object text in the Puck document (propsBindingsJson, apiBindingsJson, harnessBindingsJson, and related binding fields). Values inside those binding objects are real JSON values and do not need to be stringified independently. Validation applies bounded JSON limits, blocks unsafe object keys, checks recursive value shapes, and rejects generated sections without a valid variant binding so MCP or dashboard saves cannot silently publish runtime fallback sections.

The English docs are canonical. French content may exist in the product, but new technical documentation should update English first.

Authorization

The CMS uses Yayaw's group and role authorization model. Dashboard navigation is only a hint; server loaders, actions, services, and MCP operations must still authorize every read or mutation.

Common CMS resources:

  • page

  • sections

  • global-data

  • media

  • components

  • global-variables

  • email-template

Organization members normally receive list/read access for organization-scoped content. Managers, admins, owners, and superadmins receive manage access according to their group role bindings.

Control Plane

Operational CMS workflows should share service logic across the dashboard, MCP, CLI scripts, and tests when they are exposed outside the UI.

Current control-plane coverage includes:

  • page operations

  • component catalog operations

  • reusable section operations

  • MCP page drafting

  • CMS data operations

  • media generation operations

  • design token operations

  • transactional email template operations

  • billing catalog operations used by CMS variables

When adding a CMS feature, decide whether trusted MCP clients should operate it. If yes, add typed schemas, a reason for writes, audit records, authorization checks, and documentation updates. If no, document why the feature is intentionally dashboard-only.

Operational Rules

  • Store reusable content as published data, media, sections, or templates.

  • Keep page documents as composition documents, not duplicated content stores.

  • Do not execute DB-stored component source code.

  • Do not store media binaries in Postgres.

  • Keep public design tokens scoped outside dashboard and auth routes.

  • Keep global CMS data and organization CMS data scoped explicitly.

  • Revalidate affected dashboard and public runtime paths after publish/archive.

  • Treat generated assistant files as derived artifacts; update content/llm/llm-source.md first and regenerate them.

Validation

Useful checks after CMS documentation or CMS behavior changes:

bun run docs:generate
bun run docs:check-links
bun run docs:check-translations
bun run docs:llm:generate
bun run docs:llm:check
bun run check
bunx tsc --noEmit

Run domain tests as needed when implementation changes touch pages, sections, data models, media, components, tokens, or email templates.