Files
AndreaSlopFotografie/aidlc-docs/_shared/reverse-engineering/architecture.md
T
SluijsensandClaude Opus 5.5 db2fa89b90 Adds AI-DLC inception docs for the front-end shell feature
Workspace detection, reverse engineering of web/, requirements with
answered verification questions, the execution plan and the open
application design questions for the frontend-shell feature.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 13:03:26 +02:00

5.1 KiB

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.

Architecture Diagram

graph TD
    Main["main.tsx: ChakraProvider + ThemeProvider + RouterProvider"] --> Root["routes/__root.tsx: HeadContent + AppShell + Devtools"]
    Root --> Shell["components/AppShell.tsx"]
    Shell --> Nav["NavigationBar (+ NavLink, MobileNav, navItems)"]
    Shell --> Outlet["Outlet (active page route)"]
    Shell --> Footer["Footer (placeholder)"]
    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
    Seo -.-> Home
    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;

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.

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
  • 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
  • Type: Application

components/AppShell.tsx

  • Purpose: Application shell
  • Responsibilities: Renders NavigationBar, <Outlet />, Footer. No <main> landmark, skip link or to-top button yet
  • 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)
  • Type: Application

components/Footer.tsx

  • Purpose: Site footer
  • Responsibilities: Placeholder copyright line only; uses Tailwind-style classNames that have no effect (Tailwind is not installed)
  • 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
  • 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)

seo.ts

  • Purpose: Head tag helpers
  • Responsibilities: pageHead({title, description}) for route head options; siteHead for site-wide Open Graph tags
  • Type: Application (utility)

Data Flow

sequenceDiagram
    box rgba(246,224,94,0.4) Browser
      participant V as Visitor
    end
    box rgba(99,179,237,0.4) SPA
      participant R as Router
      participant S as AppShell
      participant P as Page route
    end
    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

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.

Integration Points

  • External APIs: None yet (planned .NET API for content and contact form)
  • Databases: None
  • Third-party Services: Outbound links only — Facebook, Instagram profiles

Infrastructure Components

  • CDK Stacks: None
  • Deployment Model: Not defined yet; output is a static Vite build (dist/)
  • Networking: N/A