Files
AndreaSlopFotografie/aidlc-docs/_shared/reverse-engineering/architecture.md
T
SluijsensandClaude Opus 5.5 b5fd83256d Loads the light logo after the page load
Lazy loading saved its bytes during page load, but left the logo empty for a
moment when navigating to the homepage on a wide screen. Also adds the second
unit's code summary and the shared docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:56:13 +01:00

165 lines
13 KiB
Markdown

# 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
```mermaid
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)
- **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
```mermaid
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; server rules still to be changed in unit 3 of prerendering). 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