Skip to content

Site Intent, Scaffold, And App Responsibilities

Purpose

This policy defines the clean boundary between:

  1. oves-sites as the site content and intent layer
  2. scaffolding as the translation layer
  3. generated ISR apps as the serving layer

This boundary exists to prevent content decisions from being hardcoded into generators or hand-patched into generated apps.

Role Of oves-sites

oves-sites is the canonical source of truth for:

  • site routes and page existence
  • page-level intent
  • content selections
  • registered page-theme choice when a page requires a theme
  • registered block choice and block props when a page is block-composed
  • editorial copy, curation, and link targets

oves-sites must not be treated as executable app code. It declares what should be rendered, not how React code is authored.

Role Of Scaffolding

Scaffolding is a translation layer.

It is responsible for:

  • validating intent against canonical contracts
  • mapping registered page themes to approved page templates
  • mapping registered block identifiers to approved block-library components
  • passing intent-owned props through to those registered components
  • generating app files and config consistently

Scaffolding must not:

  • invent page content
  • choose one specific block when the intent did not declare that block
  • split one page's visible copy across multiple unrelated intent locations unless that split is part of the contract
  • become a shadow source of truth for page composition

If scaffolding contains a hardcoded component selection for a content page, that is contamination and must be removed.

Role Of Generated Apps

Generated apps are delivery artifacts.

They are responsible for:

  • serving the composed pages
  • importing approved shared components and blocks
  • connecting runtime data sources and environment configuration
  • providing deployable site output

Generated apps must not become the durable source of page composition or editorial intent.

Direct edits to site-app page code are out of bounds for normal workflow. If the rendered output is wrong, the fix belongs in intent or in scaffold translation rules, not as a hand-authored site-app patch.

Required Pattern

The required ownership model is:

  1. oves-sites declares page intent
  2. scaffold translates intent into registered themes and blocks
  3. generated apps serve the translated result

The required transfer model is:

apps = scaffold(site_intent, registered_page_themes, registered_blocks)

Required Workflow

The required workflow is intent-first, scaffold-last:

  1. change route, page, theme, block, copy, and link intent in oves-sites
  2. adjust scaffold translation only when the declared contract cannot yet express the intended result
  3. regenerate downstream app output from scaffold

No direct site-app code change is an acceptable source-of-truth for site composition.

For block-composed pages, the intent must identify the registered block and provide its props.

For theme-driven pages, the intent must identify the registered page theme and provide its content/layout inputs.

The canonical page contract is:

  • pages.<pageKey>.theme
  • pages.<pageKey>.props

The scaffold may validate, normalize, and translate those definitions, but it must not invent a parallel page-shape contract.

Anti-Patterns

The following are explicitly disallowed:

  • a scaffold function that always imports one specific block for a page type without reading that choice from intent
  • a generated app page that is hand-edited to select a different block than the intent/scaffold path declares
  • a request to "just patch the site app" instead of correcting intent or scaffold
  • page copy split between uiCopy and page-block props when the copy is owned entirely by the block
  • compatibility mirrors becoming the de facto contract instead of the canonical contract path

Transitional Rule

Legacy intent shapes may be normalized temporarily for compatibility, but the direction of cleanup must always be:

  • more declarative intent
  • less bespoke scaffold branching
  • less generated-app drift

Any new page pattern must be added through a registered theme/block translation model, not through another page-specific hardcoded scaffold shortcut.