Files
AndreaSlopFotografie/aidlc-docs/_shared/reverse-engineering/architecture.md
T
SluijsensandClaude Opus 5.5 e013f1436b Shares the Instagram block between pages
Moves InstagramGrid out of the homepage sections and gives it its own
content module, so the portfolio can show the same block. The homepage
renders exactly as before; the tiles keep reusing the intro and review
photos, so each photo keeps one description.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 21:32:48 +01:00

11 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 + six sections"]
    Outlet --> About["routes/over-mij.tsx: about page"]
    Outlet --> Placeholders["portfolio, contact, privacyverklaring: PageIntro"]
    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"]
    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,Placeholders,Hero,Sections,Form page;
    class Content,NavData,Seo,Theme,Blocks 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 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; 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/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)
  • 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)

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)
  • 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
  • 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 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