Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/inception/application-design/services.md
T
SluijsensandClaude Opus 5.5 b5b7f3b3db Adds application design for the front-end shell feature
Component boundaries, interfaces, services and dependencies for the
shell: footer, back-to-top, skip link, status pages, page intro,
shared RouterLink, content folder and navigation module. Includes the
answered design questions and the revised site content requirement.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 23:20:41 +02:00

2.6 KiB

Services — frontend-shell

There is no back-end or service layer in this SPA. The cross-cutting "services" the shell relies on are configuration-level and listed here with how they are orchestrated.

Routing service (TanStack Router)

  • Configured in: main.tsx (createRouter) and routes/__root.tsx (createRootRoute)
  • Responsibilities:
    • File-based route tree, including the four new placeholder routes.
    • Scroll restoration (scrollRestoration: true): a new navigation starts at the top, and back/forward restores the previous position (FR-08).
    • Not found: the root route's notFoundComponent: NotFound. For an unknown URL, the root component (AppShell) keeps rendering and NotFound appears in its <Outlet>, so the shell stays visible. Verified in @tanstack/react-router Match.js: a global not-found renders through the root match's Outlet.
    • Errors: defaultErrorComponent: ErrorPage on the router, plus errorComponent: ErrorPage on the root.
      • An error in a page route is caught at that page's match, inside the shell.
      • An error in the shell itself falls back to the root's boundary and renders ErrorPage without the shell. This is a deliberate fail-safe (SECURITY-15).

Head management service

  • Configured in: seo.ts and each route's head; rendered by HeadContent in the root layout
  • Responsibilities:
    • Per-page title and description via pageHead; site-wide Open Graph tags via siteHead.
    • The 404 page sets its own title plus robots: noindex. A global not-found has no route of its own whose head could do this, so the mechanism is settled in Functional Design.

Content provisioning

  • Today: static modules in content/ (siteContent, heroContent)
  • Orchestration (application design Q3 = A):
    • AppShell imports siteContent and passes it to Footer.
    • The home route passes heroContent and siteContent.socials to Hero.
    • Components never import content themselves.
  • Later: the import points (AppShell, the home route) are replaced by route loaders or API calls. The components and types stay the same.

Scroll state

  • useScrolledPast is the one scroll-listening primitive (passive listener). It is used by NavigationBar (150px threshold) and BackToTop (60% of the viewport).

Theme service (Chakra system)

  • theme.ts with createSystem(defaultConfig, config)
  • New and overridden recipes are merged into Chakra's default config. Components consume them through Link variant="subtle", SkipNavLink, useRecipe({ key: 'iconControl' }) and LinkButton.