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>
108 lines
5.1 KiB
Markdown
108 lines
5.1 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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 `className`s 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
|
|
|
|
```mermaid
|
|
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
|