# kleva-j/portfolio_v4 architecture

> Architecture diagram of the GitHub repository kleva-j/portfolio_v4, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kleva-j/portfolio_v4
- Repository: https://github.com/kleva-j/portfolio_v4

## Overview

##### Project type and purpose
- This is a content-driven portfolio website built with Next.js 15.1 and Tailwind CSS.
- It uses Next.js’s App Router (app/ folder), MDX files in the content/ folder as its “CMS,” and generates Open Graph images via a server route (app/og/route.tsx).
- Its main goal is to serve a blog/portfolio using SSG/SSR and dynamic route rendering.

##### File structure
- Top-level folders:
- app/       → Next.js App Router for pages, layouts, error UI, dynamic routes (posts, snippets, OG routes)
- content/   → MDX files organized by topic and type; acts as your content source
- lib/       → Utility functions and site config for data fetching, font loading, constant definitions
- public/    → Static assets (fonts, images organized by content)
- layout/    → Global header component
- Config files:
- next.config.ts, tsconfig.json, postcss.config.mjs, tailwind.config.js (implicit)
- Scripts & dependencies:
- package.json (pnpm), .env.example → environment variables for SITE_URL and OG metadata.

##### README for additional insights
- Confirms use of Next.js and Tailwind, environment variable setup, local dev commands, and that it’s a work-in-progress portfolio.

##### Main components
a. Browser / Client
b. Next.js Server (for SSR/SSG):
- App Router
- Dynamic route handler (app/og/route.tsx)
- Static page generator (build-time MDX → HTML)
c. Content Source:
- .mdx files under content/
- lib/post.ts and mdx-components.tsx for transforming MDX → React
d. Component Library:
- components/ui (Tailwind-styled primitives)
e. Styling Pipeline:
- tailwind.css + postcss → global.css
f. Assets:
- public/fonts, public/images
g. Configuration & Env:
- next.config.ts, tailwind.config.js, .env
h. Deployment (e.g., Vercel / static hosting)

##### Relationships & interactions
- Browser requests a URL
→ Next.js App Router picks page/component in app/
→ If static, it serves pre-generated HTML from content/ (SSG)
→ If dynamic (e.g., post/[slug]), it runs getStaticPaths/Props logic in lib/post.ts
→ React tree is composed of layout.tsx → page.tsx → UI components → MDX content
→ CSS is injected from global.css and Tailwind classes
→ OG route: request to /og triggers app/og/route.tsx to render an image on the fly
- Build pipeline:
- MDX content + mdx-components.tsx → React component AST → static HTML
- tailwind CLI via postcss builds CSS

##### Architectural patterns & design principles
- File-based routing (Next.js App Router)
- Content as data pattern (treat MDX files as headless CMS)
- Component-driven UI (atomic Tailwind UI primitives)
- SSG/ISR for performance and SEO
- Single code repo: “monorepo” style flat structure (no separate backend)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Browser / Client"]:::client

    %% Runtime Layer
    subgraph "Next.js Runtime" 
        direction TB
        AppRouter["Next.js App Router"]:::runtime
        OGRoute["Dynamic OG Image Route\n(/og)"]:::runtime
    end

    %% Content Layer
    subgraph "Content Layer"
        direction TB
        MDXStore["MDX Content Store"]:::data
        MDXUtils["MDX Processing Utilities"]:::data
    end

    %% Build Pipeline
    subgraph "Build Pipeline" 
        direction TB
        StaticGen["Static Page Generator (SSG)"]:::pipeline
        CSSBuild["Styling Pipeline\n(Tailwind + PostCSS)"]:::pipeline
    end

    %% UI Library
    subgraph "UI Library"
        direction TB
        ComponentsUI["React Components & UI Library"]:::runtime
    end

    %% Assets & Config
    subgraph "Assets & Config"
        direction TB
        StaticAssets["Static Assets"]:::assets
        ConfigEnv["Configuration & Env"]:::assets
    end

    %% Header
    Header["Global Header Layout"]:::runtime

    %% Font Loading
    FontLoad["Font Loading"]:::data

    %% Site Config & Utils
    SiteConfig["Site Configuration & Constants"]:::data

    %% Flows
    Browser -->|"requests URL"| AppRouter
    AppRouter -->|"serves SSG HTML"| StaticGen
    StaticGen -->|"reads MDX content"| MDXStore
    MDXStore -->|"transforms via"| MDXUtils
    MDXUtils --> StaticGen
    AppRouter -->|"renders React tree"| ComponentsUI
    AppRouter -->|"invokes header"| Header
    AppRouter -->|"injects CSS from"| CSSBuild
    CSSBuild -->|"processes tailwind.css"| CSSBuild
    CSSBuild --> AppRouter
    Browser -->|"requests OG image"| OGRoute
    OGRoute --> MDXUtils

    Browser -->|"loads assets"| StaticAssets

    MDXStore -->|"loads fonts"| FontLoad
    AppRouter -->|"reads config"| SiteConfig
    ConfigEnv --> AppRouter

    %% Click Events
    click AppRouter "https://github.com/kleva-j/portfolio_v4/tree/main/app/"
    click OGRoute "https://github.com/kleva-j/portfolio_v4/blob/main/app/og/route.tsx"
    click MDXStore "https://github.com/kleva-j/portfolio_v4/tree/main/content/"
    click MDXUtils "https://github.com/kleva-j/portfolio_v4/blob/main/lib/post.ts"
    click MDXUtils "https://github.com/kleva-j/portfolio_v4/blob/main/mdx-components.tsx"
    click ComponentsUI "https://github.com/kleva-j/portfolio_v4/tree/main/components/ui/"
    click ComponentsUI "https://github.com/kleva-j/portfolio_v4/tree/main/components/icons/"
    click ComponentsUI "https://github.com/kleva-j/portfolio_v4/tree/main/components/snippet/"
    click ComponentsUI "https://github.com/kleva-j/portfolio_v4/blob/main/components/theme-provider.tsx"
    click ComponentsUI "https://github.com/kleva-j/portfolio_v4/blob/main/components/theme-toggle.tsx"
    click ComponentsUI "https://github.com/kleva-j/portfolio_v4/blob/main/components/search-params.tsx"
    click Header "https://github.com/kleva-j/portfolio_v4/blob/main/layout/header.tsx"
    click CSSBuild "https://github.com/kleva-j/portfolio_v4/blob/main/app/global.css"
    click CSSBuild "https://github.com/kleva-j/portfolio_v4/blob/main/postcss.config.mjs"
    click FontLoad "https://github.com/kleva-j/portfolio_v4/blob/main/lib/fonts.ts"
    click SiteConfig "https://github.com/kleva-j/portfolio_v4/blob/main/lib/site/config.ts"
    click SiteConfig "https://github.com/kleva-j/portfolio_v4/blob/main/lib/constant.ts"
    click SiteConfig "https://github.com/kleva-j/portfolio_v4/blob/main/lib/utils.ts"
    click StaticAssets "https://github.com/kleva-j/portfolio_v4/tree/main/public/fonts/"
    click StaticAssets "https://github.com/kleva-j/portfolio_v4/tree/main/public/images/"
    click ConfigEnv "https://github.com/kleva-j/portfolio_v4/blob/main/next.config.ts"
    click ConfigEnv "https://github.com/kleva-j/portfolio_v4/blob/main/.env.example"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1
    classDef runtime fill:#BBDEFB,stroke:#2196F3,color:#0D47A1
    classDef data fill:#C8E6C9,stroke:#4CAF50,color:#1B5E20
    classDef pipeline fill:#FFF9C4,stroke:#FFEB3B,color:#F57F17
    classDef assets fill:#ECEFF1,stroke:#CFD8DC,color:#37474F
```
