Files
AndreaSlopFotografie/aidlc-docs/_shared/reverse-engineering/architecture.md
T
SluijsensandClaude Opus 5.5 b6d5a85e41 Applies the owner's Lighthouse targets
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>
2026-11-01 20:07:24 +01:00

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.tsx starts Sentry (deferred) and hydrates the prerendered document with StartClient; router.tsx creates the router (scroll restoration, default error component); ChakraProvider (light only) and the fonts are in the document shell of routes/__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, NotFound and ErrorPage; document shell (shellComponent, prerendering); routes/$.tsx is the catch-all for unknown URLs (prerendered as 404.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 from mainNav; without JavaScript a <noscript> link opens the menu through :target CSS (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; routeChanged closes 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 (lazy ContactForm behind ContactFormGate, mailto fallback); the Instagram block is the shared components/InstagramGrid (fixed tiles linking to the profile, content from instagramContent.ts), also used on the portfolio
  • Type: Application

Shared section building blocks

  • Purpose: Reusable pieces extracted during homepage-sections; HomeSection was renamed to PageSection and MediaText/Eyebrow were extracted in over-mij-page
  • Responsibilities: PageSection (section frame: aria-labelledby, tone paper/alt, width default/narrow/full, spacing default/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 (Chakra Dialog, wrap-around browsing, keys, swipe, preloading, load-error note), FilterBar (toggle buttons, filterControl recipe)
  • 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 while siteContent.contactForm.enabled is 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.ts imports shootTypes (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 (via config/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 (generates deploy/iis/web.config and nginx confs; a test checks they are in sync), sitemap plugin, test seed; prerendering adds pageFiles.ts, inlineScripts.ts, externalizeInlineScripts.ts (post-build step: moves inline scripts to /assets/inline-<hash>.js so the CSP stays) and previewServer.ts (serves dist/client with the real server rules, 404 for unknown paths; unit 3 of prerendering: also the 301 redirects of canonicalUrls.ts and the opt-in --audit-route, which serves the 404 page with 200 at /__audit/404 for Lighthouse only); unit 3 adds canonicalUrls.ts (one page list for the URL contract) and compressibleTypes.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; semantic bg/fg/focusRing, header/content/contentNarrow sizes, header/pageTop spacing; text styles eyebrow/display/sectionTitle/lead/pageTitle; recipes container, 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 placeholder submitContactForm and 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/client holds one HTML file per page plus 404.html; dist/server is not deployed; unit 3 of prerendering: one URL contract on nginx, IIS and the preview server: /x serves x.html with 200, variants of a known page get one 301 to the canonical path with the query kept, unknown URLs and /404, /404.html give a real 404; the generated nginx block has its own gzip configuration; production upload in three passes (assets, then all HTML and web.config, then deletion of stale files, deploy/upload-production.sh) after deploy/check-artifact.sh; deploy/verify-deployment.sh checks 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