Skip to content

MPA public site (Razor Pages + htmx)

Architecture

The public WorkWingman site is a server-rendered Multi-Page App (MPA):

  • ASP.NET Razor Pages for HTML generation
  • htmx for progressive enhancement (partial updates, boosted navigation)

This is a STANDING architecture rule:

Surface Stack
Content sites / CMS / admin htmx + Razor Pages
Desktop app product Angular SPA

Do not rebuild the public site as an Angular SPA.

htmx version

  • htmx 2.0 migration is complete on branch WING-207 (wt/WT-e33f/WING-207-mpa).
  • Upstream htmx 4.0.0-beta5/6 exists (confirmed under WING-244/245) and is not adopted.
  • hx-boost is used for public site navigation.
  • /Admin pages opt out of boosting.
  • Regression coverage: admin unboosted, public boosted.

Why Admin opts out

CSP silently blocks unpkg-hosted htmx on /Admin. Self-hosting htmx would have enabled unintended hx-boost on admin forms. Explicit opt-out was chosen instead of enabling boost on admin.

Content Security Policy (CSP)

  • CSP is strict.
  • Angular-style inlineCritical CSS is incompatible with this CSP → inlineCritical: false.
  • Nonce CSP breaks deferred CSS that relies on inline onload handlers (those handlers cannot be nonced).

Sticky chrome / layout offsets

  • Site header height derives from the CSS variable --nav-h: 70px (src/WorkWingman.Site/wwwroot/css/site.css) — never hard-code offsets (a stale 57px assumption caused layout bugs; one session measured ~79px rendered incl. borders — TODO(verify) rendered height).
  • Scroll/offset values must derive from the actual header height.

Content source

  • Page content comes from WingCMS.
  • GCS bucket is the source of truth.
  • Pages render CMS content server-side.

Branching hazard

Site lanes/branches have carried an unrelated-histories hazard. Base new site work on:

wt/WT-e33f/WING-207-mpa

Deploy

  • Deployed as a Cloud Run service (see release-pipeline doc).
  • Fronted by Cloudflare.
Item Note
WING-207 htmx 2.0 migration (complete on wt/WT-e33f/WING-207-mpa)
WING-244 / WING-245 Confirmed htmx 4.x beta upstream; not adopted
Release pipeline Cloud Run deploy details live in the release-pipeline doc