Files
AndreaSlopFotografie/aidlc-docs/_shared/reverse-engineering/code-structure.md
T
SluijsensandClaude Opus 5.5 18bf0311ef Adds the shared gallery building blocks
A masonry photo grid that keeps the reading order (pure CSS, no measuring
in the browser), an accessible lightbox on Chakra's Dialog with wrap-around
browsing, keys, swipe and preloading, and a filter bar of toggle buttons.
They work on generic gallery items, so other pages can use them. The swipe
logic moves out of the hero into a shared hook; the hero behaves as before.
The rules behind them live in pure helpers with property-based tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 23:22:43 +01:00

11 KiB
Raw Blame History

Code Structure

Build System

  • Type: pnpm (packageManager: pnpm@12.11.2, lockfile web/pnpm-lock.yaml)
  • Configuration:
    • web/package.json — scripts dev, build (tsc && vite build), preview, test (vitest + coverage), lint, format:check, audit:deps, audit:dev, lighthouse, server-config, and check (all of them in sequence)
    • web/vite.config.ts — TanStack Router plugin (autoCodeSplitting) before React plugin, sitemap plugin, security headers on dev/preview, Vitest config (jsdom, 20 s timeout, 100% coverage threshold for src/lib/**, seo.ts, sitemap.ts)
    • web/tsconfig.json — bundler mode, @/* → src/*
    • web/eslint.config.js — JS + typescript-eslint + react-hooks + jsx-a11y recommended
    • web/.prettierrc — 4 spaces, single quotes, semicolons
    • web/lighthouserc.cjs / .desktop.cjs — Lighthouse CI against pnpm preview (accessibility and best practices 1.0, performance 0.9; home mobile 0.8)
    • .gitea/workflows/continuous_integration.yaml — jobs check, deploy-test, lighthouse, deploy-production

Key Classes/Modules

graph TD
    Root["routes/__root.tsx"] --> AppShell["components/AppShell.tsx"]
    AppShell --> NavigationBar["NavigationBar/NavigationBar.tsx"]
    AppShell --> Footer["Footer/Footer.tsx"]
    AppShell --> BackToTop["BackToTop/BackToTop.tsx"]
    AppShell --> Umami["Analytics/UmamiAnalytics.tsx"]
    NavigationBar --> NavLink["NavigationBar/NavLink.tsx"]
    NavigationBar --> MobileNav["NavigationBar/MobileNav.tsx"]
    NavigationBar --> navigation["navigation.ts"]
    Footer --> navigation
    Index["routes/index.tsx"] --> Hero["Hero/Hero.tsx"]
    Hero --> HeroArrows["Hero/HeroArrows.tsx"]
    Hero --> HeroPause["Hero/HeroPauseButton.tsx"]
    Hero --> HeroSocials["Hero/HeroSocials.tsx"]
    Hero --> useHeroSlider["Hero/useHeroSlider.ts"]
    Hero --> LinkButton["components/LinkButton.tsx"]
    LinkButton --> RouterLink["components/RouterLink.tsx"]
    Index --> HomeParts["home/*: IntroGallery, AboutBlock, Pricing, Testimonials, ContactSection; shared InstagramGrid"]
    HomeParts --> PageSection["PageSection/PageSection.tsx"]
    HomeParts --> SectionHeading["SectionHeading/SectionHeading.tsx"]
    HomeParts --> Reveal["Reveal/Reveal.tsx"]
    HomeParts --> FramedImage["FramedImage/FramedImage.tsx"]
    FramedImage --> DeferredImage["DeferredImage/DeferredImage.tsx"]
    HomeParts --> DeferredImage
    Placeholder["routes/over-mij.tsx and other placeholders"] --> PageIntro["PageIntro/PageIntro.tsx"]
    classDef shell fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef page fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef util fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
    class Root,AppShell,NavigationBar,Footer,BackToTop,Umami,NavLink,MobileNav shell;
    class Index,Hero,HeroArrows,HeroPause,HeroSocials,Placeholder,PageIntro,HomeParts page;
    class navigation,useHeroSlider,LinkButton,RouterLink,PageSection,SectionHeading,Reveal,FramedImage,DeferredImage util;

Text alternative: the root route renders AppShell (NavigationBar, Footer, BackToTop, Umami); NavigationBar and Footer read navigation.ts; the index route renders the Hero and the six home sections, which are built from the shared PageSection, SectionHeading, Reveal, FramedImage and DeferredImage blocks; placeholder routes render PageIntro.

Existing Files Inventory

Candidates for modification are marked with ★ for the over-mij-page feature.

  • web/index.html — HTML entry; static fallback head for non-JS crawlers
  • web/src/main.tsx — bootstrap
  • web/src/routeTree.gen.ts — generated (do not edit)
  • web/src/routes/__root.tsx — root layout, site head, 404/error
  • web/src/routes/index.tsx — home (/): Hero + six sections, ?pakket= search param
  • web/src/routes/over-mij.tsx — the about page (indexed; AboutPage JSON-LD)
  • web/src/components/about/* — AboutIntro, StorySection
  • web/src/components/shoots/* — ShootList, ShootBlock (soorten-fotoshoots page)
  • web/src/components/{CallToAction,RichParagraph}/ — shared closing block; paragraph with inline links
  • web/src/content/{shootTypes,shootTypesPageContent}.ts — shoot types (also used by the portfolio filters) and page texts; web/src/assets/shoots/ — 4:5 shoot photos
  • web/src/lib/shootLinks.ts — contact and portfolio link targets per shoot type
  • web/src/components/PhotoDuo/PhotoDuo.tsx — two photos side by side
  • web/src/content/aboutContent.ts — about page content; web/src/assets/about/* — portrait and duo photos; web/public/og-over-mij.jpg — preview image
  • web/src/routes/soorten-fotoshoots.tsx — the shoot types page
  • web/src/routes/{portfolio,contact,privacyverklaring}.tsx — placeholders with PageIntro
  • web/src/components/AppShell.tsx — shell
  • web/src/components/NavigationBar/* — header, NavLink, MobileNav
  • web/src/components/Footer/* — footer, FooterColumn, FooterLink
  • web/src/components/Hero/* — hero slider, arrows, pause button, socials, slider hook
  • web/src/components/home/* — five homepage sections (AboutBlock is the closest relative of the Over mij page's first block)
  • web/src/components/InstagramGrid/InstagramGrid.tsx — Instagram block, shared by the homepage and the portfolio (moved from home/ in portfolio-page)
  • ★ web/src/components/PageSection/PageSection.tsx — section frame for any page (was HomeSection)
  • ★ web/src/components/MediaText/MediaText.tsx, Eyebrow/Eyebrow.tsx — framed photo next to text; accent label
  • ★ web/src/components/SectionHeading/SectionHeading.tsx — eyebrow + h2 + lead
  • ★ web/src/components/FramedImage/FramedImage.tsx, DeferredImage/DeferredImage.tsx, Reveal/Reveal.tsx — photo blocks and fade-in
  • web/src/components/ContactForm/* — contact form and gate
  • web/src/components/BackToTop/BackToTop.tsx — back-to-top button
  • web/src/components/Analytics/UmamiAnalytics.tsx — Umami script injection
  • ★ web/src/components/PageIntro/PageIntro.tsx — page head block (eyebrow, h1, intro)
  • web/src/components/StatusPage/* — StatusPage layout, NotFound, ErrorPage
  • ★ web/src/components/LinkButton.tsx, RouterLink.tsx — router links (button style / Chakra-wrapped)
  • ★ web/src/content/types.ts — content interfaces (API shape)
  • ★ web/src/content/*.ts — static content (siteContent, heroContent, homeContent (exports introPhotos), instagramContent, packages, testimonials, socialPlatforms)
  • web/src/contact/* — contact form types and placeholder submit
  • web/src/hooks/* — useRouteFocus, useScrolledPast, useInView, usePageLoaded, useReveal, useSwipe (shared by the hero and the lightbox)
  • web/src/components/{PortfolioGrid,Lightbox,FilterBar}/ — gallery building blocks (portfolio-page unit 2): masonry grid in reading order (CSS only), lightbox on Chakra Dialog (lazy-loadable default export), single-choice toggle buttons; generic over GalleryItem / FilterOption
  • web/src/lib/*.ts — pure helpers with tests
  • web/src/monitoring/* — Sentry/Umami config and loader
  • web/src/navigation.ts — RoutePath, mainNav, footerNav
  • ★ web/src/seo.ts, sitePages.ts, sitemap.ts — SEO (/over-mij is indexed: false today)
  • ★ web/lighthouserc.cjs / .desktop.cjs — own list of indexed/noindex paths, guarded by a test
  • web/src/theme.ts, web/src/recipes/*.ts — design system
  • web/src/test/* — renderWithProviders, axe matcher, fast-check arbitraries, fakeIntersectionObserver, setup
  • web/src/assets/* — hero photos (8), home/ (intro 1–4, andrea, deco 1–2, two review photos), light/dark logos
  • web/config/securityHeaders.ts — CSP
  • web/config/serverConfig.ts, writeServerConfig.ts, sitemapPlugin.ts, testSeed.ts
  • web/deploy/iis/web.config, web/deploy/nginx/*.conf — generated server configs
  • web/public/* — favicon, logo, og-image, robots.txt, icons.svg

Design Patterns

API-shaped static content

  • Location: content/types.ts + content/*.ts
  • Purpose: Hard-coded today, swappable for API responses later
  • Implementation: Plain data objects typed with interfaces, passed to components as props from the route (or AppShell)

Pure helpers with property-based tests

  • Location: lib/, seo.ts, sitemap.ts
  • Purpose: Logic that decides what is shown (e.g. invalid social → hidden, invalid e-mail → column omitted) lives outside components and is tested with fast-check
  • Implementation: Small exported functions, 100% coverage threshold, shared arbitraries in test/arbitraries.ts

Design tokens + recipes

  • Location: theme.ts, recipes/
  • Purpose: Single source for colours, fonts, spacing, motion; reusable component variants
  • Implementation: defineConfig tokens/semanticTokens/textStyles, defineRecipe + useRecipe

Section composition

  • Location: components/home/* on top of PageSection, MediaText, SectionHeading, Reveal, FramedImage, DeferredImage
  • Purpose: Each section is a thin component that gets its content as a prop and composes the shared blocks; the h2 id links the section landmark (aria-labelledby)
  • Implementation: One TITLE_ID constant per section; data-testid on the section root; validity filters in lib/ (e.g. visiblePackages) decide what is rendered

Deferred below-the-fold images

  • Location: DeferredImage, usePageLoaded, useInView
  • Purpose: Protect the largest contentful paint; photos load only after the load event and near the viewport, with intrinsic width/height reserving space

Page registry

  • Location: sitePages.ts, typed by RoutePath
  • Purpose: One source for head tags and the sitemap; indexed: false for placeholders

Configuration as code for hosting

  • Location: config/securityHeaders.ts → config/serverConfig.ts → deploy/
  • Purpose: Same headers in dev, preview, nginx (test) and IIS (production); a test guards drift

Accessibility by default

  • Location: across components; test/axe.ts in component tests; Lighthouse in CI
  • Implementation: landmarks, skip link, focus management, live regions, visible focus ring, 44px targets, reduced motion

Critical Dependencies

@chakra-ui/react ^3.37.0

  • Usage: All layout and styling; typegen from theme.ts on install

@tanstack/react-router ^1.170.39 (+ router-plugin ^1.168.40)

  • Usage: File-based routes, Link, Outlet, HeadContent, typed RoutePath

@sentry/react ^11.8.0

  • Usage: Error reporting, lazy-loaded after the load event

@iconify/react ^6.0.2 + @iconify-icons/ant-design 2.0.1

  • Usage: Offline icons (bundled at build time)