Files
AndreaSlopFotografie/aidlc-docs/_shared/reverse-engineering/architecture.md
T

13 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; desktop links and full-screen mobile menu from mainNav
  • 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 (reveal once, immediately 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

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