Site Framework Architecture

Site Framework Architecture

Motivation

Site presentation needs stable contracts even when content storage and hosting change. The core owns normalized content, media, routes, section registries and provider interfaces. Domain presentation belongs in template packages; infrastructure bindings belong in adapters.

CMS-managed sites use one publication per build. This avoids mixing content and media revisions when a new publication becomes current during rendering. A configured source is explicit: inline snapshot, file or endpoint. Repository-level fallback composition is a separate contract and does not add fallback to the build input.

Architectural Diagram

flowchart TD
  CMS[Publishing system: content authority] --> P[Immutable publication]
  P --> B[Build: identity, revision and image checks]
  B --> C[Core site contracts]
  C --> H[Hotel template and Astro pages]
  H --> S[Static HTML and machine-readable outputs]
  P --> A[Optional Cloudflare projection adapter]
  A --> R[Rebuildable D1 and R2 read models]
  S --> V[Visitor]
  V --> I[Explicit contact and analytics handlers]

Trade-offs & Decisions

One authority, rebuildable projections

When a publishing system owns shared content, D1/R2 projections and static outputs are derived data. Consumers do not edit the same shared content independently. Staging verifies snapshot payload integrity before promotion; rollback selects a previously verified revision. Readers requiring content/media consistency open one revision-scoped read session rather than asking for the current head repeatedly.

Static output with explicit dynamic handlers

Static pages avoid requiring a server for every page view. Contact and analytics require explicit server integration and configured providers. The hotel package supports static Pages output and a separate API build target; Pages Functions are another host integration. Missing mail or verification bindings must fail instead of reporting simulated success.

Core, domain and provider boundaries

The core contains access, search, AI context, commerce and analytics contracts. Optional UI is imported through Studio subpaths; providers are injected. Hotel routes and booking presentation live in the hotel package. Cloudflare D1/R2 bindings, event sinks and HTTP integration adapters live in the Cloudflare package. OAuth, payment processing, customer content and deployment configuration remain host responsibilities.

Image integrity and compatibility

The common build requires image hashes, fetches each image once and renders from pinned bytes. CMS authentication headers are not forwarded to image origins. The original publication remains available for receipt comparison. The hotel wrapper retains a migration path for older feeds without hashes; supplied hashes are still checked, and a snapshot declaring SHA-256 integrity cannot use that exception. Full integrity requires hashes in the publishing contract.

Shared themes and analytics preferences

Hotel themes are CMS configuration rather than visitor preferences. Shared theme helpers validate registered presets and CSS inputs. Analytics collection follows the consent controller; host integrations must start and stop vendors when effective consent changes, including withdrawal. Core consent defaults to opt-in and respects saved refusal and DNT/GPC. The hotel host selects opt-in for English and opt-out for Japanese; the shared library does not infer policy from language.

Canonical documentation and public aggregation

This repository owns its technical documentation. The root manifest lists curated public pages for one-way aggregation. Historical inventories, customer evidence, operator records, private guides and secrets are excluded from that list. The portal’s source approval process remains separate from this manifest. English is canonical; Japanese can be supplied through sourceJa, with English fallback until a translation is available.