Files
AndreaSlopFotografie/aidlc-docs/_shared/reverse-engineering/architecture.md
T
SluijsensandClaude Opus 5.5 c81dcd3979 Adds the inception docs and design for the homepage sections
Refreshes the shared reverse engineering docs, adds the requirements,
application design and units for the homepage-sections feature, and
updates the static design: live prices and form fields, the new
Lieve woorden block and the coming-soon gate over the contact form.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 23:46:30 +02:00

7.6 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["main.tsx: Sentry start, router, ChakraProvider"] --> 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"]
    Outlet --> Placeholders["over-mij, portfolio, soorten-fotoshoots, contact, privacyverklaring: PageIntro"]
    Home --> Hero["Hero (HeroArrows, HeroPauseButton, HeroSocials, useHeroSlider)"]
    Content["content/: siteContent, heroContent, 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,Placeholders,Hero page;
    class Content,NavData,Seo,Theme support;

Text alternative: main.tsx starts Sentry and mounts the router; the root route renders AppShell (skip link, NavigationBar, the page via Outlet, Footer, BackToTop, Umami); the home route renders the Hero, the other routes render placeholder PageIntros; content, navigation, SEO and theme modules support all of it.

Component Descriptions

main.tsx

  • Purpose: Application bootstrap
  • Responsibilities: Starts Sentry (deferred), creates the router (scroll restoration, default error component), mounts ChakraProvider (light only), loads self-hosted fonts, removes static fallback head tags
  • 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
  • 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; desktop links and full-screen mobile menu from mainNav
  • 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/PageIntro/, StatusPage/

  • Purpose: Shared page building blocks
  • Responsibilities: PageIntro — eyebrow, the page's h1 and an intro (used by placeholders); StatusPage — layout for 404 and error pages
  • Type: Application

content/

  • Purpose: Static content until the CMS API exists
  • Responsibilities: types.ts (API-shaped interfaces), siteContent.ts (footer intro, socials, e-mail parts), heroContent.ts (title, tagline, CTA, slides), socialPlatforms.ts (platform → name + offline icon)
  • Type: Application (data)

lib/

  • Purpose: Pure, fully tested helpers
  • Responsibilities: emailAddress, visibleSocials, copyrightLine, slidesToLoad, backToTopThreshold
  • Type: Application (utility, 100% coverage threshold)

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
  • Type: Infrastructure-as-code (small)

theme.ts / recipes/

  • Purpose: Design system
  • Responsibilities: Colour, font, spacing, easing, duration, z-index tokens; semantic bg/fg/focusRing, header/content/pageTop sizes; eyebrow/display/pageTitle text styles; recipes container, link (subtle), linkButton (outline/accent/light), iconControl, 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 — design README: POST /api/contact with { naam, email, onderwerp, bericht })
  • 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 dist/ build. 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