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
| Surface | Route | Purpose |
|---|---|---|
| CMS dashboard | /dashboard/content | Content screen: key numbers, page views and what needs attention |
| Pages | /dashboard/content/pages | Public and organization page composition |
| Documentation | /dashboard/content/documentation | Versioned bilingual Fumadocs content and navigation |
| Sections | /dashboard/content/sections | Reusable page sections, generated recipes, and form sections |
| Data models | /dashboard/content/data-models | Typed CMS model definitions |
| Data entries | /dashboard/content/data | Published singleton and collection content |
| Media | /dashboard/content/media | Organization-scoped binary assets and generated images |
| Components | /dashboard/content/components | UI component registry, previews, and imports |
| Design tokens | /dashboard/content/design-tokens | Runtime public-theme token overrides |
| Email templates | /dashboard/content/email-templates | React Email transactional templates |
Content Stack
The CMS is layered deliberately:
Data models define typed fields, localization rules, and cardinality.
Data entries publish shared values such as header menus, footer menus, and site variables.
Media assets provide durable public URLs for selected or generated files.
Components define the reusable UI inventory and recipe renderers.
Sections define reusable page units with neutral example content and editable inputs.
Pages compose layout nodes, component references, and published section references into public or organization-member routes, then fill section inputs through page-level bindings.
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.
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:
Create or update the structured source in data models, data entries, or media.
Build a reusable section when the content should appear on more than one page.
Compose the page in the Puck editor using built-in layout nodes, section references, and direct component references only when needed.
Publish the page or section after validation diagnostics are clean.
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:
yayaw_cms_context_get(read) returns, for the requestedscope(defaultorganization) andorgId, the art-direction vocabulary (creative composition tokens, page layout options, page design tokens, example recipes,formSection, andcatalogProductSection; skip it withincludeVocabulary: 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.yayaw_cms_page_draft(write) creates the draft page in one call:name, optionalpath,slug,channel,locales,defaultLocale,titleByLocale,seo,layout,designTokens(global public pages only), and 1–24sections. Each section either creates a new composition section (kind: "create"with adefinition) or reuses a published section of the scope (kind: "reuse"withsectionSlug; 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.pageSlugwithexpectedRevisionIdadds a new draft revision to an existing page instead.dryRun: truevalidates without writing. The result returns the page (id,path,slug,revisionId,validationStatus), short-lived signed preview URLs per locale, and theyayaw_pages_publisharguments.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_publicationsand render the publishedPuckPageDocumentV1section 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 repairedpage-level
PageSectionbindings override section fixture props at runtime, so a catalog section can stay generic while each page instance carries the final localized contentliteral component and section props accept bounded JSON values directly, including nested arrays, objects, and
null; recursivevalueShapecontracts validate nested fields while legacy stringified JSON remains readabledata bindings resolve published global or organization CMS data entries
media bindings use the stored public URL from
media_assetspublic 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
legalvarianttransactional 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:
pagesectionsglobal-datamediacomponentsglobal-variablesemail-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.mdfirst 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 --noEmitRun domain tests as needed when implementation changes touch pages, sections, data models, media, components, tokens, or email templates.