Adds the first unit's code summary and updates the shared docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-31 20:28:41 +01:00
co-authored by Claude Opus 5.5
parent d6f8eb6c8e
commit 8dc120e78c
10 changed files with 119 additions and 29 deletions
@@ -7,7 +7,7 @@ A single client-side React SPA (`web/`) built with Vite. Routing is file-based v
```mermaid
graph TD
Main["main.tsx: Sentry start, router, ChakraProvider"] --> Root["routes/__root.tsx: HeadContent, AppShell, 404 and error components"]
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)"]
@@ -41,17 +41,17 @@ graph TD
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.
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
### main.tsx
### client.tsx, router.tsx (replace main.tsx; prerendering)
- **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
- **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`
- **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
@@ -108,7 +108,7 @@ Text alternative: main.tsx starts Sentry and mounts the router; the root route r
### hooks/
- **Purpose**: Shared behaviour
- **Responsibilities**: `useRouteFocus`, `useScrolledPast`, `useInView` (IntersectionObserver), `usePageLoaded` (after the load event), `useReveal` (reveal once, immediately with reduced motion)
- **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
@@ -123,7 +123,7 @@ Text alternative: main.tsx starts Sentry and mounts the router; the root route r
### 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
- **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/
@@ -159,6 +159,6 @@ Text alternative: a visitor navigates, the router renders the root layout (AppSh
## 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)
- **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