Documents the CMS-host-serves-everything decision and proposes the host injection plan

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-15 15:15:17 +01:00
co-authored by Claude Sonnet 5.5
parent ba7288526b
commit ee973477de
5 changed files with 92 additions and 21 deletions
+1 -1
View File
@@ -1,6 +1,6 @@
# Andrea Slop Fotografie
Photography website made with .NET and React for Andrea Slop Fotografie. The site (in [web/](web/)) is a React single-page app (Vite, TanStack Start prerendering, Chakra UI v3) that is prerendered to static HTML at build time. On the test host it is served by the SLP CMS host (.NET), on production by IIS (planned).
Photography website made with .NET and React for Andrea Slop Fotografie. The site (in [web/](web/)) is a React single-page app (Vite, TanStack Start prerendering, Chakra UI v3) that is prerendered to static HTML at build time. On the test host it is served by the SLP CMS host (.NET), on production the same CMS host behind an IIS pass-through (planned): the host serves the pages, `/admin` and `/api/v1/*`.
## Set-up
+16 -15
View File
@@ -1,17 +1,18 @@
# Active Features
| Type | Name | Status | Branch | Affected Components | Session Start |
| ------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| Bug | [hero-carousel-announce-and-pause](bugs/hero-carousel-announce-and-pause/bug-fix.md) | ✅ Complete | fix/hero-carousel-announce-and-pause | web/src/components/Hero (Hero, HeroArrows, useHeroSlider) | 2026-10-19 |
| Feature | frontend-shell | ✅ Complete | feature/frontend-shell | web/src (AppShell, NavigationBar, Footer, Hero socials, new BackToTop/SkipLink/404/error pages, routes, theme.ts, main.tsx), web/vite.config.js, web/package.json | 2026-10-14 |
| Feature | homepage-sections | ✅ Complete | feature/homepage-sections | web/src/routes/index.tsx, new homepage section components, web/src/content (types + static content), possibly web/config/securityHeaders.ts (contact form) | 2026-10-19 |
| Feature | over-mij-page | ✅ Complete | feature/over-mij-page | web/src/routes/over-mij.tsx, web/src/content, possibly shared components (PageIntro, FramedImage, SectionHeading) and web/src/seo.ts | 2026-10-22 |
| Feature | soorten-fotoshoots-page | ✅ Complete | feature/soorten-fotoshoots-page | web/src/routes/soorten-fotoshoots.tsx, new web/src/content/shootTypes.ts, new web/src/assets/shoots/, new shared CallToAction, MediaText (reverse prop), Pricing (id="prijzen" only), siteContent (service area), own entries in sitePages.ts / lighthouserc.cjs, JSON-LD via the shared webPage() helper in seo.ts | 2026-10-24 |
| Feature | contact-page | ✅ Complete | feature/contact-page | web/src/routes/contact.tsx, web/src/content, possibly ContactForm/ContactSection, PageIntro, MediaText/FramedImage, web/src/seo.ts, sitePages/sitemap | 2026-10-24 |
| Feature | portfolio-page | ✅ Complete | feature/portfolio-page (based on master after over-mij merge; worktree ../AndreaSlopFotografie-portfolio) | web/src/routes/portfolio.tsx, web/src/content, new PortfolioGrid + Lightbox, InstagramGrid (moved to shared), own entries in sitePages.ts / lighthouserc.cjs, ImageGallery JSON-LD via the shared webPage() helper | 2026-10-24 |
| Feature | shoot-type-pages | ✅ Complete (content follow-up: [content-pending.md](features/shoot-type-pages/content-pending.md)) | feature/shoot-type-pages (worktree ../AndreaSlopFotografie-shoot-type-pages) | new route(s) per shoot type under web/src/routes, web/src/content (shootTypes.ts extension, timeline content), shared Timeline component, links from soorten-fotoshoots, seo.ts (webPage helper), sitePages.ts / sitemap, lighthouserc.cjs | 2026-10-29 |
| Feature | prerendering | ✅ Complete (merged, PR #14) | feature/prerendering (worktree ../AndreaSlopFotografie-prerendering) | web/vite.config.ts, web/src/main.tsx, web/index.html, web/config/serverConfig.ts + web/deploy, CI workflow, web/lighthouserc.cjs, possibly Reveal/useReveal and hooks using media queries | 2026-10-31 |
| Feature | testimonials-redesign | ✅ Complete (merged, PR #16) | feature/testimonials-redesign (worktree ../AndreaSlopFotografie-testimonials-redesign) | web/src/components/home/Testimonials (Testimonials, TestimonialSlide, TestimonialCarousel), web/src/recipes/carouselControl.ts, web/src/content (Testimonial type, testimonials.ts), possibly SectionHeading, LAYOUT.md, unit/e2e tests that reference the dots | 2026-11-05 |
| Feature | cms-api-foundation | ✅ Complete (merged PR #17, 2026-11-10; follow-ups: ASF production, contact feature) | feature/cms-api-foundation (worktree ../AndreaSlopFotografie-cms-api-foundation) | Cross-repo: feature briefs for the SlpModularCms repo (new Api.AndreaSlopFotografie client, per-site theming, per-site module set); in this repo only docs, later web integration (CMS serves the site) | 2026-11-05 |
| Feature | contact-form-cms | 🔵 Inception | feature/contact-form-cms (worktree ../AndreaSlopFotografie-contact-form) | web/src/components/ContactForm, ContactFormGate, web/src/contact (submitContactForm), new web/src/cms-client (copied headless package), web/config/securityHeaders.ts, content/siteContent contactForm switch | 2026-11-10 |
| Feature | asf-packages-cms | 🔵 Construction | feature/asf-packages-cms (worktree ../AndreaSlopFotografie-packages, based on feature/contact-form-cms) | web/config (offerings, fetchOfferings), web/src/content (packages, snapshot, types), Pricing + PriceBanner + PriceTopBar (two banners, centred card rows), PackagesProvider (live refresh), CI build-test job and nightly test build, docs/ (CMS integration, deploy and CI, go-live checklist) | 2026-11-12 |
| Type | Name | Status | Branch | Affected Components | Session Start |
| ------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| Bug | [hero-carousel-announce-and-pause](bugs/hero-carousel-announce-and-pause/bug-fix.md) | ✅ Complete | fix/hero-carousel-announce-and-pause | web/src/components/Hero (Hero, HeroArrows, useHeroSlider) | 2026-10-19 |
| Feature | frontend-shell | ✅ Complete | feature/frontend-shell | web/src (AppShell, NavigationBar, Footer, Hero socials, new BackToTop/SkipLink/404/error pages, routes, theme.ts, main.tsx), web/vite.config.js, web/package.json | 2026-10-14 |
| Feature | homepage-sections | ✅ Complete | feature/homepage-sections | web/src/routes/index.tsx, new homepage section components, web/src/content (types + static content), possibly web/config/securityHeaders.ts (contact form) | 2026-10-19 |
| Feature | over-mij-page | ✅ Complete | feature/over-mij-page | web/src/routes/over-mij.tsx, web/src/content, possibly shared components (PageIntro, FramedImage, SectionHeading) and web/src/seo.ts | 2026-10-22 |
| Feature | soorten-fotoshoots-page | ✅ Complete | feature/soorten-fotoshoots-page | web/src/routes/soorten-fotoshoots.tsx, new web/src/content/shootTypes.ts, new web/src/assets/shoots/, new shared CallToAction, MediaText (reverse prop), Pricing (id="prijzen" only), siteContent (service area), own entries in sitePages.ts / lighthouserc.cjs, JSON-LD via the shared webPage() helper in seo.ts | 2026-10-24 |
| Feature | contact-page | ✅ Complete | feature/contact-page | web/src/routes/contact.tsx, web/src/content, possibly ContactForm/ContactSection, PageIntro, MediaText/FramedImage, web/src/seo.ts, sitePages/sitemap | 2026-10-24 |
| Feature | portfolio-page | ✅ Complete | feature/portfolio-page (based on master after over-mij merge; worktree ../AndreaSlopFotografie-portfolio) | web/src/routes/portfolio.tsx, web/src/content, new PortfolioGrid + Lightbox, InstagramGrid (moved to shared), own entries in sitePages.ts / lighthouserc.cjs, ImageGallery JSON-LD via the shared webPage() helper | 2026-10-24 |
| Feature | shoot-type-pages | ✅ Complete (content follow-up: [content-pending.md](features/shoot-type-pages/content-pending.md)) | feature/shoot-type-pages (worktree ../AndreaSlopFotografie-shoot-type-pages) | new route(s) per shoot type under web/src/routes, web/src/content (shootTypes.ts extension, timeline content), shared Timeline component, links from soorten-fotoshoots, seo.ts (webPage helper), sitePages.ts / sitemap, lighthouserc.cjs | 2026-10-29 |
| Feature | prerendering | ✅ Complete (merged, PR #14) | feature/prerendering (worktree ../AndreaSlopFotografie-prerendering) | web/vite.config.ts, web/src/main.tsx, web/index.html, web/config/serverConfig.ts + web/deploy, CI workflow, web/lighthouserc.cjs, possibly Reveal/useReveal and hooks using media queries | 2026-10-31 |
| Feature | testimonials-redesign | ✅ Complete (merged, PR #16) | feature/testimonials-redesign (worktree ../AndreaSlopFotografie-testimonials-redesign) | web/src/components/home/Testimonials (Testimonials, TestimonialSlide, TestimonialCarousel), web/src/recipes/carouselControl.ts, web/src/content (Testimonial type, testimonials.ts), possibly SectionHeading, LAYOUT.md, unit/e2e tests that reference the dots | 2026-11-05 |
| Feature | cms-api-foundation | ✅ Complete (merged PR #17, 2026-11-10; follow-ups: ASF production, contact feature) | feature/cms-api-foundation (worktree ../AndreaSlopFotografie-cms-api-foundation) | Cross-repo: feature briefs for the SlpModularCms repo (new Api.AndreaSlopFotografie client, per-site theming, per-site module set); in this repo only docs, later web integration (CMS serves the site) | 2026-11-05 |
| Feature | contact-form-cms | 🔵 Inception | feature/contact-form-cms (worktree ../AndreaSlopFotografie-contact-form) | web/src/components/ContactForm, ContactFormGate, web/src/contact (submitContactForm), new web/src/cms-client (copied headless package), web/config/securityHeaders.ts, content/siteContent contactForm switch | 2026-11-10 |
| Feature | asf-packages-cms | 🔵 Construction | feature/asf-packages-cms (worktree ../AndreaSlopFotografie-packages, based on feature/contact-form-cms) | web/config (offerings, fetchOfferings), web/src/content (packages, snapshot, types), Pricing + PriceBanner + PriceTopBar (two banners, centred card rows), PackagesProvider (live refresh), CI build-test job and nightly test build, docs/ (CMS integration, deploy and CI, go-live checklist) | 2026-11-12 |
| Feature | asf-cms-host-injection | 📝 Plan proposal, awaiting Bryan ([plan.md](features/asf-cms-host-injection/plan.md)); starts after the current merges | (none yet) | web (PackagesProvider, build markers, neutral HTML), preview server stand-in injector, e2e/contract tests; host side in the SlpModularCms repo | 2026-11-15 |
@@ -0,0 +1,66 @@
# Plan (proposal, not approved): the CMS host injects CMS data into the prerendered ASF pages
Status: PROPOSAL for Bryan. Nothing is built. It starts as a separate feature after the current merges (contact-form-cms, then asf-packages-cms), not through them. To be agreed with SLP Modular CMS - SMC - Main, who owns the host side.
## Why
Hosting decision (2026-11-15): the CMS host is the one entry of the website and serves the prerendered pages, `/admin` and `/api/v1/*`; IIS passes everything to it. A CMS change (packages, banners, later gallery and hero) must then be visible to search engines at once, with no rebuild. The host injects the current data into the prerendered HTML through markers (as on SLP, 60 s cache).
## What is CMS data on the pages today
Packages: the price cards (home), the shoot list and shoot blocks, the "welke shoot" choices of the contact form, the `?pakket=` check, the offer price in the JSON-LD of the shoot pages. Banners: the slim top bar and the band under the cards. See [docs/cms-integration.md](../../../docs/cms-integration.md).
## Proposal
### 1. Three kinds of markers (built into the page by the ASF build, filled by the host)
- **Data block**, one per page: `<script type="application/json" id="cms-data">…</script>` holding the raw answers of `GET /api/v1/offerings` and both banners. The host replaces its content with the current answers (JSON-escaped: `<`, `>`, `&`, U+2028/2029). It is a non-executable block, so the CSP stays as it is and the build step that moves inline scripts treats it as data (as it does for `ld+json`).
- **Region**, for lists that differ in length (the cards, the banners): a wrapper `<div data-cms-region="offerings">` whose content is the neutral HTML. The host replaces everything between `<!--cms:offerings-->` and `<!--/cms:offerings-->` (written into the wrapper by the build; React cannot emit comments, so the build writes them through `dangerouslySetInnerHTML`).
- **Inline value**, for a single price or name inside a sentence: `<span data-cms-price="newborn">€ 185</span>`. The host replaces the text.
- **JSON-LD price** of a shoot page: the `ld+json` block gets `data-cms-offer="newborn"`; the host sets `offers.price` from the live package (or removes `offers` when the package is gone or has no readable price).
- The same marker format as SLP, if SLP already has one (to be confirmed by SMC).
### 2. Neutral HTML in the markers
The build puts crawlable, simple semantic HTML between the markers (package name, price, features, a plain link to `/?pakket=<slug>#contact`; the banner as an `aside`), written from the baked data by one pure function (`web/src/lib/neutralHtml.ts`, all text escaped). The host produces the same markup from live data (template in C#; the ASF repo delivers the spec and golden files, SMC implements, a contract test in each repo checks both sides against the same fixtures). Light static CSS in the page makes it look acceptable (the section is below the fold).
Why not exact copies of the styled cards: Chakra/Emotion class names and styles are generated at build time, a C# template cannot reproduce them.
### 3. Hydration: read the JSON, do not fetch
- `PackagesProvider` takes its initial state from the data block (reusing `mapOfferings`, `mapBanner`, `mapTopBanner`), not from the baked import and not from a fetch after hydration. Without a block (preview, tests, a host that does not inject) it falls back to the baked data plus the live fetch it has today, so nothing is lost.
- Regions are not hydrated by React (`dangerouslySetInnerHTML` with `suppressHydrationWarning`, so React keeps the server DOM). After hydration (`useHydrated`) the styled React components render into the region and replace the neutral HTML. So the first paint is the neutral HTML, and a brief change of look follows; the cards are below the fold, and the region keeps a minimum height to avoid a layout shift.
- Inline values hydrate directly from the same data (`suppressHydrationWarning` for the formatting difference).
- The contact form choices and `?pakket=` read the same state, so they agree with what the host injected.
### 4. Hydration and contract tests (per marker, before anything ships)
- Build test: every expected marker exists exactly once per page, in the final `dist/` (after the script-moving step), and the neutral HTML equals what the pure function gives.
- E2E in real Chrome with a stand-in injector in the preview server (same algorithm as the host, fixtures with more, fewer and different packages, with and without banners, an unreadable price, a hostile text such as `<script>`): no hydration or console error, the final DOM shows the injected data, the layout shift stays under the CLS limit.
- Fail-safe tests: marker missing, data block empty or invalid, host injection off: the page shows the baked data.
- Contract tests with golden fixtures shared with the CMS repo (marker format, escaping, the neutral HTML, the JSON-LD price edit).
- Security: all CMS text is HTML-escaped by the host; the data block is escaped as above; no executable inline script appears.
### 5. Build and deploy consequences
- The build no longer needs the CMS: the baked data is only the fallback, so `build-test` with `OFFERINGS_URL` and the nightly content build can go. One artifact can serve test and production.
- Optional: the test address (`VITE_SITE_URL`) could become a host replacement like SLP's `Website:AuthoredBaseUrl`, which would make the artifact identical for test and production. Needs the injector on ASF's prerendered-pages host; to ask SMC.
- Production deploy changes with the hosting: `dist/` goes to the CMS host's prerendered-pages folder (as on test). The generated IIS config reduces to redirects and pass-through. See the Hosting section of the CMS integration doc.
- The safety net of AI-DLC: a pipeline option (debounced rebuild after a CMS change) stays possible for build-processed gallery images later.
### 6. Hero and gallery later (separate plans, same mechanism)
- **Hero (LCP):** the first slide must be in the first HTML, with the image preloaded. The host injects the slide markup and a `<link rel="preload" as="image">` into a head marker; the client slider starts from the same first slide so nothing swaps. Own plan, because the carousel is interactive.
- **Gallery:** `figure` list with image URLs, sizes and alt texts in a region (crawlable), React adds lazy loading and the lightbox after hydration. Images are served same-origin by the CMS host (CSP `img-src 'self'`).
## Order of work (after approval)
1. Marker spec and golden fixtures (ASF repo), agreed with SMC.
2. Pure neutral-HTML function, build writes the markers, build tests.
3. `PackagesProvider` reads the data block, regions, inline values, JSON-LD price; stand-in injector in the preview server; e2e and fail-safe tests.
4. SMC implements the injector with the same fixtures; test on ASF test.
5. Hosting switch for production (separate), then remove the nightly content build.
## Open questions
- For SMC: the marker format SLP uses today; how the injector reads and edits JSON and `ld+json`; behaviour when data or a marker is missing (must fail open: serve the baked page); caching and ETag; whether `AuthoredBaseUrl` can also run on the prerendered-pages host.
- For Bryan: accept a brief look change of the cards on first paint (neutral HTML, then styled)? The alternative is one set of cards styled by plain CSS and owned by the host, with no React in those regions; that makes first paint exact but gives up the router links and the Reveal animation of the cards, and puts every design change in two places.
+6 -3
View File
@@ -15,7 +15,7 @@ Source: `GET /api/v1/offerings`. One list feeds the price cards on the home page
- **Featured package** (the star in the CMS admin, field `featured`): the card gets a heidegroen rule along its top, a heidegroen border and a small "Uitgelicht" tab on the top edge (`PriceCard`). The tab is positioned on the border, so the cards of a row keep the same layout. Any number of cards may be featured.
- **Description, price note and button label** (`description`, `priceNote`, `ctaLabel`) are optional in the CMS and the site does not use them: they are not shown and a card never depends on them (empty, `null` or absent all give the same card; covered by tests).
- **Scheduling in the CMS:** the API only returns packages that are live at the moment of the request (switched on and inside their from/to dates), so the site shows them and nothing else. The baked list reflects the moment of the build; the live refresh after hydration corrects it for every visitor, and the nightly build corrects it for search engines. A package that goes live or expires between two builds is therefore right in the browser but can be stale in the HTML until the next build.
- **Keep the snapshot current** when the real packages change (prices, features), because production builds use it (see "Reverse proxy" below).
- **Keep the snapshot current** when the real packages change (prices, features), because production builds use it (see "Hosting" below).
## Banners (OfferingBanner)
@@ -36,10 +36,13 @@ Both follow the same rules as the packages: baked into the HTML at build time, r
`GET /api/v1/contact-messages/token` and `POST /api/v1/contact-messages` through the headless `web/src/cms-client`. The form is behind the switch `contactForm.enabled` in `web/src/content/siteContent.ts` (off means the "Binnenkort" gate and no request to the server). Details and the go-live conditions are in `aidlc-docs/features/contact-form-cms/` and [go-live-checklist.md](go-live-checklist.md). Friendly Captcha is off at go-live.
## Reverse proxy for `/api/v1/*`
## Hosting: the CMS host serves everything
Decision (Bryan, 2026-11-15): the hosting package has one entry per website. The CMS host (Kestrel) is that entry and serves the website itself (the prerendered pages), `/admin` and `/api/v1/*`. In production IIS (or the proxy) therefore passes **all** requests to the CMS host, not only `/api/v1/*`, and serves no static files or HTML cache of its own. This holds for the test host and for ASF production alike.
- **Test (ASF):** nginx on the proxy Pi forwards everything for `test.andreaslop.nl` to the CMS host (`web/deploy/nginx/test.andreaslop.nl.proxy.conf`), which serves the site files and the API. Nothing to add.
- **Production (IIS): not in place yet.** The generated `web/deploy/iis/web.config` only serves static files, so `/api/v1/*` answers 404 there. Production needs either a reverse-proxy rule (URL Rewrite with ARR) from `/api/v1/*` to a production CMS host for ASF, or the CMS host serving the site as on test. This is a separate follow-up together with ASF production hosting. Until then the production build uses the committed snapshot and the live calls fail safely (the baked list stays; the browser console shows the 404). Change the rule in `web/config/serverConfig.ts` and run `pnpm server-config`; never edit the generated files.
- **Production: not in place yet.** The generated `web/deploy/iis/web.config` and the FTP upload of static files (`web/deploy/upload-production.sh`) still describe the old idea of IIS serving the files. They have to change with the production hosting: IIS keeps only the redirects (www, HTTPS) and the pass-through to the CMS host, and the prerendered `dist/` goes to the CMS host's prerendered-pages folder as on test. Security headers then come from the CMS host (as on test). This is part of the production hosting work, not of the packages feature. Until then production builds use the committed snapshot and the live calls fail safely (the baked list stays; the browser console shows a 404 for the API). Change generated server files only in `web/config/serverConfig.ts` and run `pnpm server-config`.
- **Next step (planned, separate feature after the current merges):** the CMS host injects the current packages, banners and later gallery and hero into the prerendered pages through markers, so a CMS change is visible to search engines at once and no rebuild is needed for it. The plan is in `aidlc-docs/features/asf-cms-host-injection/plan.md`; nothing of it is built yet. The browser-side live refresh described above stays as the safety net until then.
## Environment and variables
+3 -2
View File
@@ -10,7 +10,7 @@ What must be true before the CMS-driven parts of the site go to production. Brya
## Packages and banners
- [ ] Production hosting (IIS) in place and `/api/v1/*` reverse-proxied to a production CMS host for ASF, or the CMS host serving the site ([cms-integration.md](cms-integration.md)). Without it production keeps the committed snapshot and the console shows a 404 per page view.
- [ ] Production hosting in place with the CMS host as the one entry of the website: IIS passes ALL requests to the CMS host (not only `/api/v1/*`) and serves no static files itself; the prerendered `dist/` is deployed to the CMS host ([cms-integration.md](cms-integration.md), "Hosting"). The generated IIS config and the production upload script are updated for this. Without it production keeps the committed snapshot and the console shows a 404 per page view for the API.
- [ ] `web/src/content/offerings.snapshot.json` holds the real, current packages (production builds use it).
- [ ] The production CMS holds the real packages. The test CMS prices must never end up in the production artifact (it is built without `OFFERINGS_URL`).
@@ -35,6 +35,7 @@ The contact form must not go live before the statement does.
## Other open items
- ASF production hosting on IIS (separate feature).
- ASF production hosting: CMS host behind IIS pass-through (separate feature, see above).
- Host injection of CMS data into the prerendered pages (plan: `aidlc-docs/features/asf-cms-host-injection/plan.md`, after the current merges).
- First ASF administrator and removal of the setup token (CMS).
- Messages created by the Playwright test run in the ASF test CMS are archived by Bryan.