Skip to content

Site Engine

Status: Draft for review

Purpose

Own public-site content, managed-site composition/publishing, themes, navigation, SEO/localization and the headless content/site API capability reserved for Custom-plan contracts.

Owns

  • Site instances and delivery mode (MANAGED or HEADLESS)
  • Managed site shell: headers, footers, navigation, theme and global component defaults
  • Pages, page templates, sections, reusable sections and component variants
  • Functional component bindings to commerce/capability data
  • Content, media references and SEO metadata; localized representations follow Internationalization Engine contracts
  • Draft/preview/publish/version/rollback lifecycle
  • Redirects and sitemap/robots metadata generation
  • Headless content delivery contract for Custom plan

Non-goals

It does not own offering/business data, payment/booking rules, ad campaign state or arbitrary tenant JavaScript execution. It does not make headless delivery available to Starter/Growth/Pro.

API contract — functional surface

These are contract-level resources and operations, not final controller/file names.

Method Route Primary actor Contract intent
GET /api/public/v1/site/bootstrap Visitor Resolve site theme, navigation, locale and public configuration.
GET /api/public/v1/pages/{slug} Visitor/Custom Site Return published page/content representation for resolved site.
GET /api/tenant/v1/sites Tenant Admin/Editor List tenant sites.
POST /api/tenant/v1/sites Tenant Owner/Admin Create managed site subject to plan limits.
PATCH /api/tenant/v1/sites/{id}/theme Content Editor Configure allowed theme tokens.
PUT /api/tenant/v1/sites/{id}/navigation Content Editor Manage navigation data independently of header variant.
POST /api/tenant/v1/sites/{id}/pages Content Editor Create page from blank/template.
PUT /api/tenant/v1/pages/{id}/sections Content Editor Compose/reorder/configure page sections.
POST /api/tenant/v1/pages/{id}/preview Content Editor Create/resolve preview version.
POST /api/tenant/v1/sites/{id}/publish Content Editor/Tenant Admin Publish validated site version.
POST /api/tenant/v1/sites/{id}/rollback Tenant Admin Rollback to prior published version.
POST /api/tenant/v1/reusable-sections Content Editor Create reusable section where entitled.
GET /api/tenant/v1/component-catalog Content Editor List entitled site/page/vertical component variants.
POST /api/tenant/v1/headless-clients Custom Tenant Owner Create scoped headless API client; rejected for non-Custom plan.

All mutating operations apply the global tenant, authorization, audit and idempotency rules where relevant.

Events

  • site.created
  • page.created
  • page.updated
  • site.published
  • site.rolled_back
  • navigation.changed
  • theme.changed
  • headless_client.created

Roles & responsibility matrix

Legend: A accountable, R responsible, C consulted, I informed, — none.

Capability Platform Admin Tenant Owner Tenant Admin Specialist/Manager Customer/Visitor
Component/template catalog A/R I I C I
Site/domain delivery choice C A/R C — I
Managed site pages/content I A C R I
Publish/rollback I A R R I
Headless client (Custom only) C A/R C — I

Dependencies

  • Platform Engine for plan/entitlement/domain/site ownership
  • Capability Engine for component/vertical metadata
  • Commerce Engine for functional component data/actions
  • Marketing Engine for campaign landing/visibility bindings
  • Integration Engine for analytics/maps/media providers
  • Internationalization Engine for site locales, translation resolution, localized routes/SEO and formatting contracts

Internationalization Contract

  • Page/site structure is shared across locales by default; translatable content is resolved by locale.
  • Sites configure enabled/default locales from tenant-enabled locales.
  • Navigation labels, page content, section copy and SEO metadata are translatable.
  • Localized slugs, canonical URLs, hreflang and locale-aware sitemaps are supported.
  • Locale-specific structural overrides are controlled capability/entitlement features, not separate duplicated sites by default.
  • Managed and Custom/headless delivery use the same localized content contract.

Security / isolation requirements

  • Only Custom contract may create HEADLESS sites or headless API clients.
  • Published site data cannot expose draft/private content.
  • Component props are schema-validated; no arbitrary script execution.
  • Publishing and rollback are audited/versioned.

Acceptance criteria

  • Tenant can create arbitrary content pages within plan limits.
  • Pages can be composed from reorderable sections and versioned variants.
  • Site-level header/footer/navigation/theme/listing defaults are independent from page sections.
  • Functional components bind to business units/offerings without duplicating commerce data.
  • Starter/Growth/Pro cannot enable headless delivery.
  • Custom site can consume the same authoritative commerce/content APIs without backend fork.