Files
AndreaSlopFotografie/aidlc-docs/_shared/reverse-engineering/code-structure.md
T
SluijsensandClaude Opus 5.5 7af2069959 Adds the shoot page layout and the shoot-type submenu
Shoot pages follow design E: breadcrumb, story blocks, process
timeline with icons, photo mosaic, FAQ, package block and booking
call to action, with per-shoot OG images. The navigation gets a
"Soorten fotoshoots" submenu (desktop panel, mobile group) built from
shootTypes, with exact current-page matching in menu, footer and
breadcrumb. A 404 under /soorten-fotoshoots/ also offers a link back
to the overview.

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

160 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```mermaid
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
navigation --> shootNavItems["lib/shootNavItems.ts"]
navigation --> shootTypes["content/shootTypes.ts"]
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,shootNavItems,shootTypes,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/shoots/ShootPage/ShootPage.tsx` — shoot page shell, `ShootPageView` in (unit 1: intro only; unit 2 adds the sections)
- `web/src/components/StructuredData/StructuredData.tsx` — JSON-LD script via `jsonLdScript`; the only `dangerouslySetInnerHTML` of the shoot pages
- `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/lib/{shootPages,shootPackage,fillPlaceholders,richTextToPlain,shootPageView}.ts` — shoot page helpers (ids and paths, package, placeholders, plain text, view), each with a test
- `web/src/lib/{shootNavItems,navCurrent,navMenuState}.ts` — navigation helpers (unit 3), each with a test: submenu items from the shoot types (`shootNavItems`), current-page and section-current matching (`isItemCurrent`, `isSectionCurrent`), menu state reducer (`navMenuReducer`, `NavMenuState`, `NavMenuEvent`; `navMenuState.ts` at 100 % coverage)
- `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/index.tsx` — the shoot types page (moved from `routes/soorten-fotoshoots.tsx`); `newborn.tsx`, `zwangerschap.tsx`, `gezin.tsx`, `loveshoot.tsx`, `portret.tsx` — one route per shoot page (`/soorten-fotoshoots/<id>`); `-shootPageSources.ts` — the sources the shoot routes share
- `web/src/content/shootPageShared.ts` — shared shoot page content (breadcrumb, process, deposit, shared FAQ items, offer texts); `web/src/content/shootPages/*.ts` — one content module per shoot page, plus `shootPages.test.ts` (content consistency)
- `web/src/test/renderApp.tsx` — `renderApp(path)` and `expectShell()` for the route tests
- `web/src/routes/portfolio.tsx` — the portfolio (indexed; `?shoot=` filter; `ImageGallery` JSON-LD); `web/src/components/portfolio/PortfolioGallery/`, `web/src/content/portfolioContent.ts`, `web/src/lib/portfolioFilters.ts`, `web/src/assets/portfolio/*` (10 photos × 2 sizes), `web/public/og-portfolio.jpg`
- `web/src/routes/{contact,privacyverklaring}.tsx` — placeholders with `PageIntro`
- `web/src/components/AppShell.tsx` — shell
- `web/src/components/NavigationBar/*` — header, NavLink (`sectionCurrent` underline for the parent of an open section), MobileNav (scrolls; Escape returns focus to the hamburger), NavSubmenu (desktop disclosure panel), MobileNavGroup (expandable shoot list on mobile), ChevronIcon
- `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/hooks/useDismiss.ts` — Escape and outside pointer down while active (`useDismiss(ref, active, onDismiss)`), used by NavSubmenu and MobileNav (unit 3)
- `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`, `NavItem` (with `children`, one level), `hasChildren`, `mainNav` (the shoot submenu comes from `shootTypes` via `shootNavItems`), `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/test/navArbitraries.ts` — navigation generators (menu events, menu states, pathnames; unit 3, not in `lib/` so the 100 % threshold does not apply); `web/src/test/navViewport.ts` — viewport helper (`matchMedia` stub and the `lg` display rules, because jsdom ignores `@media`)
- `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)