# fabianwaller/personal-website architecture

> Architecture diagram of the GitHub repository fabianwaller/personal-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fabianwaller/personal-website
- Repository: https://github.com/fabianwaller/personal-website

## Overview

##### Project type and purpose
- It’s a Next.js “personal website” combining static content (blog posts in MDX), dynamic pages (contact form, OpenGraph images, RSS, sitemap), and a component library (UI primitives in src/components/ui).
- Purpose: serve a fast, responsive portfolio/blog site with SSR/SSG plus lightweight API routes for contact and metadata feeds.

##### File structure
- Top‑level: config files (.eslintrc, tsconfig, tailwind.config), scripts (husky, lint/test workflow), README, package locks.
- posts/: markdown content for SSG.
- public/: static assets (images, PDF).
- src/app/: Next.js 13+ App Router with directories for each route (about, blog/[slug], contact, journey, projects, etc.). Contains page.tsx, route.ts (API endpoints), middleware.ts.
- src/components/: shared React UI components organized by feature and a “ui” subfolder for primitives.
- src/hooks, src/lib, src/provider: custom React hooks, utility functions, and React Context providers.
- Configuration for PostCSS, Tailwind, Jest, Lighthouse.

##### README for additional insights
- The site is deployed as a Node/SSR service (or a purely SSG export on Vercel).

##### Main components and their interactions
a. Client/Browser UI (React):
– Next.js pages in src/app render React components (from src/components and MDX components).
– Context providers (BlogPostsContext, CommandMenuContext) wrap the app.
– Client‑side interactivity (command menu, contact form).
b. Next.js Server Functions:
– SSG/SSR engine: builds pages at build time or serves dynamic pages at request time.
– API Routes:
- /contact/actions/sendContact (server action to handle form submission → external email API/spam service).
- /rss/route and /sitemap.ts (generate RSS feed and sitemap).
- /og/route (dynamic OpenGraph images).
c. Data sources:
– File system: MDX files under posts/.
– Static assets in public/.
– Potential 3rd‑party services (email service, analytics, CDN).
d. Build & Test Toolchain:
– Build: Next.js + Webpack/RSC + Tailwind via postcss.config.
– Test: Jest + React Testing Library + snapshots.
– Lint/Format: ESLint + Prettier + Husky hooks.

##### Architectural patterns & design principles
- File‑based routing (App Router) → directory = route.
- Component‑based UI with a small custom design system (ui subfolder).
- SSG for blog posts and static pages; SSR or Edge functions for dynamic routes.
- Separation of concerns: UI vs. data fetch (actions, utils) vs. providers vs. hooks.
- DX tooling: ESLint, Prettier, Jest with pre‑commit/pre‑push hooks.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser / Client Layer
    subgraph "Browser / Client" 
        direction TB
        ReactApp["React App"]:::frontend
        Layout["Root Layout"]:::frontend
        Contexts["Context Providers"]:::frontend
        Pages["Page Components"]:::frontend
        ReactApp -->|renders via| Layout
        Layout -->|wraps| Contexts
        Contexts -->|provides to| Pages
    end

    %% Next.js Server / Runtime Layer
    subgraph "Next.js Server / Runtime"
        direction TB
        AppRouter["Next.js App Router"]:::server
        StaticSSG["SSG Engine (MDX Posts)"]:::server
        DynamicSSR["SSR / Edge Functions"]:::server
        APIRoutes["API Routes"]:::server
        Middleware["Middleware"]:::server

        AppRouter -->|routes to| StaticSSG
        AppRouter -->|routes to| DynamicSSR
        AppRouter -->|routes to| APIRoutes
        AppRouter -->|passes through| Middleware
    end

    %% Data Sources Layer
    subgraph "Data Sources"
        direction TB
        MDXFiles["MDX Posts (posts/)"]:::data
        StaticAssets["Static Assets (public/)"]:::data
        MDXParser["MDX Parser"]:::data
        MDXFiles -->|parsed by| MDXParser
        MDXParser -->|provides content| StaticSSG
        StaticAssets -->|served| StaticSSG
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        EmailAPI["Email API / Spam Service"]:::external
        CDN["CDN"]:::external
        Analytics["Analytics Service"]:::external
        APIRoutes -->|sendContact uses| EmailAPI
        Pages -->|assets via| CDN
        ReactApp -->|tracks via| Analytics
    end

    %% CI/CD Layer
    subgraph "CI/CD & Toolchain"
        direction TB
        GitHubActions["GitHub Actions"]:::ci
        Build["Build (Next.js, Tailwind)"]:::ci
        Test["Test (Jest + RTL)"]:::ci
        Lint["Lint/Format (ESLint/Prettier)"]:::ci
        Hooks["Husky Hooks"]:::ci

        GitHubActions --> Build
        GitHubActions --> Test
        GitHubActions --> Lint
        Lint --> Hooks
    end

    %% Interactions
    ReactApp -->|HTTP request| AppRouter
    APIRoutes -->|returns JSON| ReactApp
    StaticSSG -->|serves HTML| ReactApp
    DynamicSSR -->|serves HTML| ReactApp

    %% Click Events
    click AppRouter "https://github.com/fabianwaller/personal-website/tree/main/src/app/"
    click Layout "https://github.com/fabianwaller/personal-website/blob/main/src/app/layout.tsx"
    click AboutPage "https://github.com/fabianwaller/personal-website/blob/main/src/app/about/page.tsx"
    click ContactPage "https://github.com/fabianwaller/personal-website/blob/main/src/app/contact/page.tsx"
    click JourneyPage "https://github.com/fabianwaller/personal-website/blob/main/src/app/journey/page.tsx"
    click ProjectsPage "https://github.com/fabianwaller/personal-website/blob/main/src/app/projects/page.tsx"
    click UsesPage "https://github.com/fabianwaller/personal-website/blob/main/src/app/uses/page.tsx"
    click HomePage "https://github.com/fabianwaller/personal-website/blob/main/src/app/page.tsx"
    click NotFound "https://github.com/fabianwaller/personal-website/blob/main/src/app/not-found.tsx"
    click BlogList "https://github.com/fabianwaller/personal-website/blob/main/src/app/blog/page.tsx"
    click BlogPost "https://github.com/fabianwaller/personal-website/blob/main/src/app/blog/[slug]/page.tsx"
    click OGImage "https://github.com/fabianwaller/personal-website/blob/main/src/app/blog/[slug]/opengraph-image.tsx"
    click TwitterImage "https://github.com/fabianwaller/personal-website/blob/main/src/app/blog/[slug]/twitter-image.tsx"
    click BlogUtils "https://github.com/fabianwaller/personal-website/blob/main/src/app/blog/utils.ts"
    click SendContact "https://github.com/fabianwaller/personal-website/blob/main/src/app/contact/actions/sendContact.ts"
    click RSSRoute "https://github.com/fabianwaller/personal-website/blob/main/src/app/rss/route.ts"
    click Sitemap "https://github.com/fabianwaller/personal-website/blob/main/src/app/sitemap.ts"
    click OGRoute "https://github.com/fabianwaller/personal-website/blob/main/src/app/og/route.tsx"
    click Robots "https://github.com/fabianwaller/personal-website/blob/main/src/app/robots.ts"
    click Middleware "https://github.com/fabianwaller/personal-website/blob/main/src/middleware.ts"
    click CommandMenu "https://github.com/fabianwaller/personal-website/blob/main/src/components/CommandMenu.tsx"
    click ContactForm "https://github.com/fabianwaller/personal-website/blob/main/src/components/ContactForm.tsx"
    click UIPrimitives "https://github.com/fabianwaller/personal-website/tree/main/src/components/ui/"
    click BlogPostsContext "https://github.com/fabianwaller/personal-website/blob/main/src/provider/BlogPostsContext.tsx"
    click CommandMenuContext "https://github.com/fabianwaller/personal-website/blob/main/src/provider/CommandMenuContext.tsx"
    click Hooks "https://github.com/fabianwaller/personal-website/blob/main/src/hooks/use-toast.ts"
    click Utils "https://github.com/fabianwaller/personal-website/blob/main/src/lib/utils.ts"
    click Escape "https://github.com/fabianwaller/personal-website/blob/main/src/lib/escape.ts"
    click MDXComponents "https://github.com/fabianwaller/personal-website/blob/main/src/mdx-components.tsx"
    click MDXPosts "https://github.com/fabianwaller/personal-website/tree/main/posts/"
    click StaticAssetsDir "https://github.com/fabianwaller/personal-website/tree/main/public/"
    click ESLintConfig "https://github.com/fabianwaller/personal-website/blob/main/.eslintrc.json"
    click TailwindConfig "https://github.com/fabianwaller/personal-website/blob/main/tailwind.config.ts"
    click PostCSSConfig "https://github.com/fabianwaller/personal-website/blob/main/postcss.config.mjs"
    click JestConfig "https://github.com/fabianwaller/personal-website/blob/main/jest.config.ts"
    click JestSetup "https://github.com/fabianwaller/personal-website/blob/main/jest.setup.js"
    click Tests "https://github.com/fabianwaller/personal-website/tree/main/__tests__/"
    click HuskyPreCommit "https://github.com/fabianwaller/personal-website/tree/main/.husky/pre-commit"
    click HuskyPrePush "https://github.com/fabianwaller/personal-website/tree/main/.husky/pre-push"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef server fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef data fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef ci fill:#E1BEE7,stroke:#333,stroke-width:1px
```
