12 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 --> 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: 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; 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
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,NotFoundandErrorPage - 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;routeChangedcloses 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(lazyContactFormbehindContactFormGate, mailto fallback); the Instagram block is the sharedcomponents/InstagramGrid(fixed tiles linking to the profile, content frominstagramContent.ts), also used on the portfolio - Type: Application
Shared section building blocks
- Purpose: Reusable pieces extracted during homepage-sections;
HomeSectionwas renamed toPageSectionandMediaText/Eyebrowwere extracted in over-mij-page - Responsibilities:
PageSection(section frame:aria-labelledby, tonepaper/alt, widthdefault/narrow/full, spacingdefault/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(ChakraDialog, wrap-around browsing, keys, swipe, preloading, load-error note),FilterBar(toggle buttons,filterControlrecipe) - 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 whilesiteContent.contactForm.enabledis 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.tsimportsshootTypes(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) - 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 (viaconfig/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(generatesdeploy/iis/web.configand 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; semanticbg/fg/focusRing,header/content/contentNarrowsizes,header/pageTopspacing; text styleseyebrow/display/sectionTitle/lead/pageTitle; recipescontainer,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 placeholdersubmitContactFormand 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