Three pages no longer need an exception and the homepage target rises to its measured score, so the gain cannot slip away unnoticed. Also adds the third unit's code summary and updates the shared docs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
14 KiB
System Architecture
System Overview
A single client-side React SPA (web/) built with Vite. Routing is file-based via TanStack Router; styling uses Chakra UI v3 with a custom system (tokens from the static design). There is no back-end, API or database; api/ is an empty placeholder for the planned .NET API. Content lives in typed TypeScript modules under web/src/content/, shaped so the API can later deliver it 1-to-1. One build serves both environments; the hostname decides whether monitoring is active.
Architecture Diagram
graph TD
Main["client.tsx: Sentry start, hydration (router.tsx: getRouter)"] --> Root["routes/__root.tsx: HeadContent, AppShell, 404 and error components"]
Root --> Shell["components/AppShell.tsx"]
Shell --> Skip["SkipNavLink and main landmark"]
Shell --> Nav["NavigationBar (NavLink, MobileNav)"]
Shell --> Outlet["Outlet (active page route)"]
Shell --> Footer["Footer (FooterColumn, FooterLink)"]
Shell --> ToTop["BackToTop"]
Shell --> Umami["UmamiAnalytics"]
Outlet --> Home["routes/index.tsx: Hero + six sections"]
Outlet --> About["routes/over-mij.tsx: about page"]
Outlet --> Portfolio["routes/portfolio.tsx: PortfolioGallery + InstagramGrid"]
Outlet --> Placeholders["contact, privacyverklaring: PageIntro"]
Outlet --> ShootPages["routes/soorten-fotoshoots/: overview and five shoot pages"]:::page
Home --> Hero["Hero (HeroArrows, HeroPauseButton, HeroSocials, useHeroSlider)"]
Home --> Sections["components/home/: IntroGallery, AboutBlock, Pricing, Testimonials, ContactSection; shared InstagramGrid"]
Sections --> Blocks["Shared blocks: PageSection, MediaText, CallToAction, RichParagraph, Eyebrow, SectionHeading, FramedImage, DeferredImage, Reveal; gallery: PortfolioGrid, Lightbox, FilterBar"]
Sections --> Form["ContactForm + ContactFormGate (lazy), contact/"]
Content["content/: siteContent, heroContent, homeContent, packages, testimonials, types"] -.-> Shell
Content -.-> Home
Nav --> NavData["navigation.ts: mainNav, footerNav"]
Footer --> NavData
Seo["seo.ts + sitePages.ts"] -.-> Root
Seo -.-> Home
Theme["theme.ts + recipes/"] -.-> Main
classDef entry fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef shell fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef page fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef support fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
class Main,Root entry;
class Shell,Skip,Nav,Footer,ToTop,Umami,Outlet shell;
class Home,About,Portfolio,Placeholders,Hero,Sections,Form page;
class Content,NavData,Seo,Theme,Blocks support;
Text alternative: client.tsx starts Sentry and hydrates the prerendered page (prerendering; router from router.tsx); the root route renders AppShell (skip link, NavigationBar, the page via Outlet, Footer, BackToTop, Umami); the home route renders the Hero and six sections built from shared blocks (one of them lazily loads the contact form); the about route renders the Over mij page; the other routes render placeholder PageIntros; the shoot pages render shoots/ShootPage, whose sections follow shootPageBands(view) (lib/shootPageBands.ts): intro, stories, process, photos, FAQ, package, closing; content, navigation, SEO and theme modules support all of it.
Component Descriptions
client.tsx, router.tsx (replace main.tsx; prerendering)
- Purpose: Application bootstrap
- Responsibilities:
client.tsxstarts Sentry (deferred) and hydrates the prerendered document withStartClient;router.tsxcreates the router (scroll restoration, default error component); ChakraProvider (light only) and the fonts are in the document shell ofroutes/__root.tsx - Type: Application
routes/__root.tsx
- Purpose: Root route / layout
- Responsibilities: Site-wide head (
siteHead: OG basics + JSON-LD),HeadContent,AppShell, dev-only router devtools,NotFoundandErrorPage; document shell (shellComponent, prerendering);routes/$.tsxis the catch-all for unknown URLs (prerendered as404.html) - Type: Application
components/AppShell.tsx
- Purpose: Application shell (LAYOUT.md "Shell")
- Responsibilities: Skip link +
<main id="main">, NavigationBar, Outlet, Footer, BackToTop, UmamiAnalytics; moves focus to main on route change (useRouteFocus) - Type: Application
components/NavigationBar/
- Purpose: Site header and navigation
- Responsibilities: Fixed header, transparent over the hero on desktop until scrolled; shrinks after scroll; logo links home (the light logo is lazy off
/until the page has loaded); desktop links and full-screen mobile menu frommainNav; without JavaScript a<noscript>link opens the menu through:targetCSS (components/NoScript/, display fallbacks) - Menu state: one
useReducer(navMenuReducer)(lib/navMenuState.ts) holds the mobile menu, its group, the desktop submenu and the focus request, so the hamburger, the panels and the route listener cannot disagree;routeChangedcloses everything (also on browser back) - Type: Application
components/Footer/
- Purpose: Site footer
- Responsibilities: Logo + intro text, Socials column, Contact column (e-mail assembled in the browser), copyright line, footer menu from
footerNav; empty columns are omitted - Type: Application
components/Hero/
- Purpose: Homepage hero slider (the only homepage section so far)
- Responsibilities: Crossfade slides, progress-driven autoplay, arrows, swipe, pause button, pause on hover/focus/hidden tab, reduced motion, live-region announcements, lazy loading of nearby slides, social icons
- Type: Application
components/home/ (homepage sections)
- Purpose: The six homepage blocks below the hero, in LAYOUT.md order
- Responsibilities:
IntroGallery(four photos, swipeable row on phones),AboutBlock(framed photo of Andrea + intro + link to/over-mij),Pricing+PriceCard(packages with "Boek" links →/?pakket=…#contact),Testimonials(+TestimonialCarousel,TestimonialSlide),ContactSection(lazyContactFormbehindContactFormGate, mailto fallback); the Instagram block is the sharedcomponents/InstagramGrid(fixed tiles linking to the profile, content frominstagramContent.ts), also used on the portfolio - Type: Application
Shared section building blocks
- Purpose: Reusable pieces extracted during homepage-sections;
HomeSectionwas renamed toPageSectionandMediaText/Eyebrowwere extracted in over-mij-page - Responsibilities:
PageSection(section frame:aria-labelledby, tonepaper/alt, widthdefault/narrow/full, spacingdefault/tight/flushTop, anchor offset),MediaText(framed photo next to a text column, design.about),Eyebrow(accent label, optionally a heading),SectionHeading(eyebrow + h2 + lead, align start/center, compact spacing),FramedImage(photo with a coloured offset block, sand by default, design.about__media),CallToAction(closing block: h2, lead, action; added in soorten-fotoshoots-page),RichParagraph(paragraph with inline links),DeferredImage(loads after page load and near the viewport, reserves space),Reveal(fade-in on scroll, content always in the DOM, reduced motion respected); gallery blocks from portfolio-page:PortfolioGrid(CSS-only masonry in reading order, first 3 photos eager),Lightbox(ChakraDialog, wrap-around browsing, keys, swipe, preloading, load-error note),FilterBar(toggle buttons,filterControlrecipe) - Type: Application (shared UI)
components/PageIntro/, StatusPage/
- Purpose: Shared page building blocks
- Responsibilities:
PageIntro— eyebrow, the page's h1 and an intro (used by placeholders; design.page-head);StatusPage— layout for 404 and error pages - Type: Application
components/ContactForm/ + contact/
- Purpose: Contact form, built ahead of the API
- Responsibilities:
ContactForm(fields, validation, honeypot + minimum fill time, reducer-driven status),ContactFormGate(dims the form under a "coming soon" notice whilesiteContent.contactForm.enabledis false);contact/submitContactForm.ts(placeholder submit),contact/types.ts(fields, limits, payload) - Type: Application
content/
- Purpose: Static content until the CMS API exists
- Responsibilities:
types.ts(API-shaped interfaces incl.ContentImage,HomeContent,PricingPackage,Testimonial),siteContent.ts(footer intro, socials, e-mail parts, contact form switch),heroContent.ts,homeContent.ts(texts and photos of the homepage sections),packages.ts,testimonials.ts,socialPlatforms.ts - Type: Application (data)
- D5 (unit 3):
navigation.tsimportsshootTypes(the submenu is built from it), so the shoot type data is in the main bundle instead of its own chunk. Measured in the Step 16 build: main chunk 150.69 → 152.58 kB gzip (+1.89 kB, limit 2.5 kB; raw 528.98 → 536.68 kB)
lib/
- Purpose: Pure, fully tested helpers
- Responsibilities:
emailAddress,visibleSocials,copyrightLine,slidesToLoad,backToTopThreshold,slideLabel,formatPrice,bookLabel,visiblePackages,visibleTestimonials,packageFromSearch,shootOptions,mailLink,validateContact,isLikelySpam,toContactPayload,contactFormReducer - Type: Application (utility, 100% coverage threshold)
hooks/
- Purpose: Shared behaviour
- Responsibilities:
useRouteFocus,useScrolledPast,useInView(IntersectionObserver),usePageLoaded(after the load event),useReveal(visible in the first render; a layout effect hides an element wholly below the viewport, which fades in once; never with reduced motion),useHydrated,useEmailAddress(prerendering: the first render equals the prerendered HTML) - Type: Application
seo.ts, sitePages.ts, sitemap.ts
- Purpose: SEO
- Responsibilities: Page registry (title, description,
indexed),pageHead(path), canonical URLs, JSON-LD, sitemap generation at build time (viaconfig/sitemapPlugin.ts) - Type: Application (utility, 100% coverage threshold)
monitoring/
- Purpose: Error reporting and analytics configuration
- Responsibilities: Hostname → environment map, Sentry DSN and origins; Sentry loaded after the load event with a queue
- Type: Application
config/ (build-time, Node)
- Purpose: Server configuration as code
- Responsibilities:
securityHeaders.ts(CSP + headers for dev/preview/prod),serverConfig.ts(generatesdeploy/iis/web.configand nginx confs; a test checks they are in sync), sitemap plugin, test seed; prerendering addspageFiles.ts,inlineScripts.ts,externalizeInlineScripts.ts(post-build step: moves inline scripts to/assets/inline-<hash>.jsso the CSP stays) andpreviewServer.ts(servesdist/clientwith the real server rules, 404 for unknown paths; unit 3 of prerendering: also the 301 redirects ofcanonicalUrls.tsand the opt-in--audit-route, which serves the 404 page with 200 at/__audit/404for Lighthouse only); unit 3 addscanonicalUrls.ts(one page list for the URL contract) andcompressibleTypes.ts(one type list for gzip and the IIS MIME pins) - Type: Infrastructure-as-code (small)
theme.ts / recipes/
- Purpose: Design system
- Responsibilities: Colour (paper/ink/accent/sand/line/error), font, spacing (
gutter,sectionY,sectionYTight,sectionHeadGap,gridGap), easing, duration (interaction,fade,reveal), z-index, shadow, gradient tokens; semanticbg/fg/focusRing,header/content/contentNarrowsizes,header/pageTopspacing; text styleseyebrow/display/sectionTitle/lead/pageTitle; recipescontainer,link(subtle/underline),linkButton(outline/accent/light, size default/fit),iconControl,carouselControl,formControl,skipNavLink - Type: Application (shared UI foundation)
Data Flow
sequenceDiagram
box rgba(246,224,94,0.4) Browser
participant V as Visitor
end
box rgba(99,179,237,0.4) SPA
participant R as Router
participant S as AppShell
participant P as Page route
end
V->>R: Open URL or click nav link
R->>S: Render root layout
S->>P: Render matched route via Outlet
P-->>R: head() title and meta from sitePages
R-->>V: Updated page, head tags, focus on main
Text alternative: a visitor navigates, the router renders the root layout (AppShell), which renders the matched page through the Outlet; the page's head() supplies title/meta from the page registry and focus moves to main.
Integration Points
- External APIs: None yet (planned .NET API for content and the contact form; the form already sends
{ naam, email, shoot, bericht }to a placeholdersubmitContactFormand stays gated off until the API exists) - Databases: None
- Third-party Services: Sentry (errors, EU ingest), Umami at analytics.slpsoftware.nl (cookieless stats), UptimeRobot (availability, external), outbound links to Facebook/Instagram
Infrastructure Components
- IaC: None beyond generated web server configs in
web/deploy/ - Deployment Model: Static prerendered build (prerendering:
dist/clientholds one HTML file per page plus404.html;dist/serveris not deployed; unit 3 of prerendering: one URL contract on nginx, IIS and the preview server:/xservesx.htmlwith 200, variants of a known page get one 301 to the canonical path with the query kept, unknown URLs and/404,/404.htmlgive a real 404; the generated nginx block has its own gzip configuration; production upload in three passes (assets, then all HTML andweb.config, then deletion of stale files,deploy/upload-production.sh) afterdeploy/check-artifact.sh;deploy/verify-deployment.shchecks the result after a deploy; the IIS rules are generated as text and are unverified until a host exists). Test: scp to nginx on a Raspberry Pi (auto on push to master). Production: FTPS to an IIS webhost (manual,release/*only, after Lighthouse) - Security headers: Strict CSP —
script-src 'self'+ Umami,connect-src 'self'+ Umami + Sentry,form-action 'self',frame-ancestors 'none'. Any third-party form or script endpoint must be added here (and regenerated into the server configs) - Networking: N/A