Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/construction/frontend-shell/functional-design/business-logic-model.md
T
SluijsensandClaude Opus 5.5 069c7cb7eb Adds AI-DLC construction docs for the front-end shell feature
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>
2026-10-18 17:05:03 +02:00

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 Footer at 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 sitePages module the route heads use, so a page can never be indexed in the sitemap and noindex in 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:

  1. 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.
  2. Dedicated address + spam filter (technique 4). Already partly in place: info@andreaslop.nl is used only for the website. Remaining step: a strict spam filter on that mailbox.
  3. CMS content: the e-mail address keeps the { user, domain } shape in the API (BR-EMAIL-01).
  4. 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.
  5. 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.
  6. Responsive images: serve smaller variants of the hero and portfolio photos per screen width (srcset). Comes with the portfolio feature, where most photos are.