Functional design, NFR requirements, code generation plan and summary, and build-and-test instructions with results. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.6 KiB
Business Logic Model — frontend-shell
The shell has four flows: content provisioning, page navigation, not-found/error rendering and the back-to-top interaction. Rules are referenced by ID from business-rules.md.
1. Content provisioning
graph TD
Site["content/siteContent"] --> Shell["AppShell"]
Hero_c["content/heroContent"] --> Home["Home route"]
Site --> Home
Shell -->|"content prop"| Footer["Footer"]
Home -->|"content + socials props"| Hero["Hero"]
Footer --> VS1["visibleSocials"]
Footer --> EA["emailAddress"]
Hero --> VS2["visibleSocials"]
classDef data fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
classDef provider fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
classDef ui fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
classDef fn fill:#9C27B0,stroke:#4a148c,stroke-width:1px,color:#000;
class Site,Hero_c data;
class Shell,Home provider;
class Footer,Hero ui;
class VS1,VS2,EA fn;
Text alternative: static content modules are imported only by AppShell and the home route, which pass them as props to Footer and Hero; both use the pure helpers to decide what to show.
- Components never import content (AD D3). Later the two import points become route loaders or API calls.
- The e-mail address is joined in
Footerat render (BR-EMAIL-01).
2. Page navigation and scroll position
sequenceDiagram
box rgba(246,224,94,0.4) Visitor
participant V as Visitor
end
box rgba(99,179,237,0.4) App
participant R as Router
participant S as AppShell
participant P as Page
end
V->>R: Click menu link
R->>S: Render matched route in main
S->>P: Render page with its head
R-->>V: Scroll to top of new page
V->>R: Browser back
R-->>V: Restore previous scroll position
Text alternative: a menu click renders the new page inside the shell and starts at the top; browser back restores the earlier scroll position (FR-08, router scroll restoration).
3. Not-found and error rendering
graph TD
Url["URL requested"] --> Match{"Route matches?"}
Match -->|"no"| NF["NotFound in main, shell stays"]
NF --> NFHead["Own title + noindex"]
Match -->|"yes"| Render{"Error while rendering?"}
Render -->|"no"| Page["Page in main"]
Render -->|"in a page"| ErrIn["ErrorPage in main, shell stays"]
Render -->|"in the shell"| ErrOut["ErrorPage without shell"]
ErrIn --> Log["console.error once"]
ErrOut --> Log
ErrIn --> Retry{"Opnieuw proberen?"}
Retry -->|"yes"| Reset["Reset boundary + invalidate router"]
Reset --> Render
Retry -->|"Terug naar home"| HomeR["Navigate to /"]
classDef decision fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef fail fill:#F44336,stroke:#b71c1c,stroke-width:1px,color:#000;
classDef action fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
class Match,Render,Retry decision;
class Page,HomeR ok;
class NF,ErrIn,ErrOut fail;
class Url,NFHead,Log,Reset action;
Text alternative: an unknown URL shows NotFound inside the shell; a page error shows ErrorPage inside the shell and a shell error shows it without the shell; errors are logged once, and the visitor can retry (re-render) or go home.
4. Back-to-top interaction
sequenceDiagram
box rgba(246,224,94,0.4) Visitor
participant V as Visitor
end
box rgba(154,230,180,0.4) Shell
participant H as useScrolledPast
participant B as BackToTop
participant M as main
end
V->>H: Scroll down
H->>B: scrollY above threshold so visible
V->>B: Click or Enter
B->>V: Scroll to top, smooth or instant
B->>M: Move focus with preventScroll
H->>B: scrollY below threshold so hidden
Text alternative: scrolling past the threshold makes the button visible; activating it scrolls to the top (instant under reduced motion), moves focus to main and the button hides again (BR-TOP-02, -05, -06).
5. Focus on page change (BR-A11Y-01)
sequenceDiagram
box rgba(246,224,94,0.4) Visitor
participant V as Visitor
end
box rgba(154,230,180,0.4) App
participant R as Router
participant F as useRouteFocus
participant M as main
end
V->>R: Follow a link or use back and forward
R->>R: Render new page and restore scroll
R->>F: Resolved with a new pathname
alt First load
F->>F: Do nothing
else Pathname changed
F->>M: Focus with preventScroll
end
M-->>V: Screen reader reads from start of content
Text alternative: after the router has rendered a page with a new pathname (not on first load), focus moves to main without scrolling, so a screen reader starts reading the new content.
6. Build-time SEO files (BR-SEO-06 to -08)
graph LR
Pages["sitePages registry"] --> Plugin["Vite sitemap plugin"]
Url["siteUrl"] --> Plugin
Plugin -->|"indexed pages only"| Xml["dist/sitemap.xml"]
Robots["public/robots.txt"] --> Dist["dist/robots.txt"]
Pages --> Test{"Test: registry equals route tree?"}
Tree["Generated route tree"] --> Test
Test -->|"no"| Fail["Test fails"]
classDef code fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef build fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef out fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
classDef check fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef fail fill:#F44336,stroke:#b71c1c,stroke-width:1px,color:#000;
class Pages,Url,Tree,Robots code;
class Plugin build;
class Xml,Dist out;
class Test check;
class Fail fail;
Text alternative: during the build a small Vite plugin turns the indexed entries of the page registry into sitemap.xml and robots.txt is copied as a static file; a test fails when the registry and the route tree list different pages.
Effort and reliability of the generated sitemap (CH Q5):
- The plugin is about 30 lines. The XML is built by the pure, property-tested function
sitemapXml. - It needs no route crawling and no extra dependency. It reads the same
sitePagesmodule the route heads use, so a page can never be indexed in the sitemap andnoindexin its head at the same time. - The only manual step is adding a new page to
sitePages. BR-SEO-07 makes the tests fail when that is forgotten.
Recommendations Outside This Feature (CQ4 = A)
Recorded so they come back with the Contact page and the .NET API:
- Contact form as the main contact channel (technique 3). The address then appears nowhere on the site. Needs the back-end: server-side sending, a honeypot field and rate limiting, and possibly a CAPTCHA.
- Dedicated address + spam filter (technique 4). Already partly in place:
info@andreaslop.nlis used only for the website. Remaining step: a strict spam filter on that mailbox. - CMS content: the e-mail address keeps the
{ user, domain }shape in the API (BR-EMAIL-01). - Old static site: as long as it is online, it exposes the address literally in its HTML. Replacing it with this site removes that source.
- Prerendering (CH Q1 = A): generate static HTML per route at build time once the real pages exist, so link previews (WhatsApp, Facebook, LinkedIn) show the right title and image per page. BR-SEO-11 keeps this possible without rework. Belongs with hosting/Operations.
- Responsive images: serve smaller variants of the hero and portfolio photos per screen width (
srcset). Comes with the portfolio feature, where most photos are.