Adds the inception docs and design for the homepage sections
Refreshes the shared reverse engineering docs, adds the requirements, application design and units for the homepage-sections feature, and updates the static design: live prices and form fields, the new Lieve woorden block and the coming-soon gate over the contact form. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,79 +1,107 @@
|
||||
# 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 theme system (tokens taken from the static design). There is no back-end, API, database or deployment pipeline yet; the README states a .NET API is planned. Content is currently hard-coded in TypeScript modules shaped so they can later come from that API.
|
||||
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
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Main["main.tsx: ChakraProvider + ThemeProvider + RouterProvider"] --> Root["routes/__root.tsx: HeadContent + AppShell + Devtools"]
|
||||
Main["main.tsx: Sentry start, router, ChakraProvider"] --> Root["routes/__root.tsx: HeadContent, AppShell, 404 and error components"]
|
||||
Root --> Shell["components/AppShell.tsx"]
|
||||
Shell --> Nav["NavigationBar (+ NavLink, MobileNav, navItems)"]
|
||||
Shell --> Skip["SkipNavLink and main landmark"]
|
||||
Shell --> Nav["NavigationBar (NavLink, MobileNav)"]
|
||||
Shell --> Outlet["Outlet (active page route)"]
|
||||
Shell --> Footer["Footer (placeholder)"]
|
||||
Shell --> Footer["Footer (FooterColumn, FooterLink)"]
|
||||
Shell --> ToTop["BackToTop"]
|
||||
Shell --> Umami["UmamiAnalytics"]
|
||||
Outlet --> Home["routes/index.tsx: Hero"]
|
||||
Outlet --> About["routes/over-mij.tsx: placeholder"]
|
||||
Home --> Hero["Hero (+ HeroArrows, HeroSocials, useHeroSlider)"]
|
||||
Hero --> Content["heroContent.ts (static content)"]
|
||||
Nav --> Scroll["hooks/useScrolledPast"]
|
||||
Theme["theme.ts + recipes/linkButton.ts"] -.-> Main
|
||||
Seo["seo.ts: pageHead / siteHead"] -.-> Root
|
||||
Outlet --> Placeholders["over-mij, portfolio, soorten-fotoshoots, contact, privacyverklaring: PageIntro"]
|
||||
Home --> Hero["Hero (HeroArrows, HeroPauseButton, HeroSocials, useHeroSlider)"]
|
||||
Content["content/: siteContent, heroContent, 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,Nav,Footer,Outlet shell;
|
||||
class Home,About,Hero page;
|
||||
class Content,Scroll,Theme,Seo support;
|
||||
class Shell,Skip,Nav,Footer,ToTop,Umami,Outlet shell;
|
||||
class Home,Placeholders,Hero page;
|
||||
class Content,NavData,Seo,Theme support;
|
||||
```
|
||||
|
||||
Text alternative: main.tsx mounts providers and the router; the root route renders AppShell (NavigationBar, the active page via Outlet, Footer); the home route renders the Hero; theme and SEO helpers support all of it.
|
||||
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, the other routes render placeholder PageIntros; content, navigation, SEO and theme modules support all of it.
|
||||
|
||||
## Component Descriptions
|
||||
### main.tsx
|
||||
- **Purpose**: Application bootstrap
|
||||
- **Responsibilities**: Creates the router, registers types, mounts ChakraProvider (custom system), next-themes ThemeProvider (light only), loads self-hosted fonts, removes static fallback head tags
|
||||
- **Dependencies**: routeTree.gen.ts, theme.ts
|
||||
- **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 tags (`siteHead`), renders `HeadContent`, `AppShell` and router devtools
|
||||
- **Dependencies**: AppShell, seo.ts
|
||||
- **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
|
||||
- **Responsibilities**: Renders NavigationBar, `<Outlet />`, Footer. No `<main>` landmark, skip link or to-top button yet
|
||||
- **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 on `/` until scrolled 150px; shrinks after scroll (desktop); swaps dark/light logo; desktop link list with animated underline (`NavLink`); hamburger button and full-screen `MobileNav` below `lg` (Escape to close, body scroll lock, clip-path reveal). `navItems.ts` is the single menu source (currently Home, Over mij)
|
||||
- **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.tsx
|
||||
### components/Footer/
|
||||
- **Purpose**: Site footer
|
||||
- **Responsibilities**: Placeholder copyright line only; uses Tailwind-style `className`s that have no effect (Tailwind is not installed)
|
||||
- **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
|
||||
- **Responsibilities**: Crossfade slides with zoom, progress bar driven autoplay, arrows, swipe, pause on hover/focus/hidden tab, reduced-motion support, social icons. Content typed in `types.ts` for future API use; `socialPlatforms.ts` maps platform keys to offline Iconify icons
|
||||
- **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
|
||||
|
||||
### theme.ts / recipes/linkButton.ts
|
||||
- **Purpose**: Design system
|
||||
- **Responsibilities**: Colour, font, spacing, easing, duration tokens; semantic `bg`/`fg`, `header` size tokens; `eyebrow`/`display` text styles; `linkButton` recipe (outline / accent / light)
|
||||
- **Type**: Application (shared UI foundation)
|
||||
### components/PageIntro/, StatusPage/
|
||||
- **Purpose**: Shared page building blocks
|
||||
- **Responsibilities**: `PageIntro` — eyebrow, the page's h1 and an intro (used by placeholders); `StatusPage` — layout for 404 and error pages
|
||||
- **Type**: Application
|
||||
|
||||
### seo.ts
|
||||
- **Purpose**: Head tag helpers
|
||||
- **Responsibilities**: `pageHead({title, description})` for route `head` options; `siteHead` for site-wide Open Graph tags
|
||||
- **Type**: Application (utility)
|
||||
### content/
|
||||
- **Purpose**: Static content until the CMS API exists
|
||||
- **Responsibilities**: `types.ts` (API-shaped interfaces), `siteContent.ts` (footer intro, socials, e-mail parts), `heroContent.ts` (title, tagline, CTA, slides), `socialPlatforms.ts` (platform → name + offline icon)
|
||||
- **Type**: Application (data)
|
||||
|
||||
### lib/
|
||||
- **Purpose**: Pure, fully tested helpers
|
||||
- **Responsibilities**: `emailAddress`, `visibleSocials`, `copyrightLine`, `slidesToLoad`, `backToTopThreshold`
|
||||
- **Type**: Application (utility, 100% coverage threshold)
|
||||
|
||||
### 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, font, spacing, easing, duration, z-index tokens; semantic `bg`/`fg`/`focusRing`, `header`/`content`/`pageTop` sizes; `eyebrow`/`display`/`pageTitle` text styles; recipes `container`, `link` (subtle), `linkButton` (outline/accent/light), `iconControl`, `skipNavLink`
|
||||
- **Type**: Application (shared UI foundation)
|
||||
|
||||
## Data Flow
|
||||
|
||||
@@ -90,18 +118,19 @@ sequenceDiagram
|
||||
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
|
||||
R-->>V: Updated page and head tags
|
||||
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 tags.
|
||||
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 contact form)
|
||||
- **External APIs**: None yet (planned .NET API for content and the contact form — design README: `POST /api/contact` with `{ naam, email, onderwerp, bericht }`)
|
||||
- **Databases**: None
|
||||
- **Third-party Services**: Outbound links only — Facebook, Instagram profiles
|
||||
- **Third-party Services**: Sentry (errors, EU ingest), Umami at analytics.slpsoftware.nl (cookieless stats), UptimeRobot (availability, external), outbound links to Facebook/Instagram
|
||||
|
||||
## Infrastructure Components
|
||||
- **CDK Stacks**: None
|
||||
- **Deployment Model**: Not defined yet; output is a static Vite build (`dist/`)
|
||||
- **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
|
||||
|
||||
Reference in New Issue
Block a user