# jakub-studio/website architecture

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

- Interactive diagram: https://gitdiagram.com/jakub-studio/website
- Repository: https://github.com/jakub-studio/website

## Overview

##### Main components of the system
- Content Management: All markdown content and copy is located in src/content (blog posts, project pages, legal pages, etc.). This represents the dynamic/static content that is rendered.
- Markdoc Integration: Markdoc related modules under src/modules/markdown (both client and server) handle the conversion and rendering of markdown content.
- API Routes: The project features API endpoints under src/pages/api (e.g., the go-redirect-service) which handle backend operations such as routing shortcuts.
- Additional Modules: There are various modules such as:
- src/modules/fs – likely for file system handling,
- src/modules/images – organizing different image assets for projects,
- src/modules/mappings – mapping project categories and software links,
- src/modules/script-handler and src/modules/source-query-tracker which also encapsulate particular platform functionalities.
- Global Configuration: Next.js configuration (next.config.js, next-env.d.ts), tailwind configuration (tailwind.config.js), and various linting and formatting files that define project style.

##### Relationships and Interactions
- The Pages Layer (in src/pages) is responsible for handling routing. These pages use the layout (from src/components/Layout.tsx) to render common elements like Navbar and Footer.
- The Content Layer in src/content is the source of textual markdown content that is processed by Markdoc. Its processing logic is implemented in the markdown modules (in src/modules/markdown), which transform raw markdown into rendered React components.
- The API layer (under src/pages/api) provides auxiliary backend functionality, such as redirect services. These endpoints are invoked by certain components or client-side logic.
- The Frontend Components interact with utility modules (e.g., src/utils.ts) and configuration files to render interfaces that adapt to different screen sizes and support theming (e.g., via TailwindCSS and components like ThemePicker in the Footer).
- The image assets are managed through dedicated modules (src/modules/images) and reference actual images stored in src/content/_images.

##### Architectural Patterns and Key Technologies
- Next.js’s routing mechanism combined with its file-based pages structure.
- A component-driven architecture using React and modular design, which separates concerns (UI components, markdown processing, content management).
- Use of serverless/API routes to complement the static pages of a personal website.
- Use of specialized modules that encapsulate business logic (e.g., handling of storage consent, managing content queries, and handling source data mapping).
- Use of TailwindCSS for styling which affects the look and feel of grouped UI components and pages.
- Markdoc for markdown transformation, making use of both “server” and “client” modules to achieve proper rendering of markdown nodes and custom tags.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend/UI Components
    subgraph "Frontend/UI"
        subgraph "Next.js Pages"
            NXPages("Next.js Pages"):::frontend
        end
        subgraph "Layout Components"
            Layout("Layout"):::frontend
            Navbar("Navbar"):::frontend
            Footer("Footer"):::frontend
            SkipToMain("SkipToMainContent"):::frontend
        end
        subgraph "Markdown Rendering Components"
            MarkdownPost("MarkdownPost"):::frontend
            Meta("Meta"):::frontend
            Post("Post"):::frontend
            MDNodes("Markdown (Nodes & Tags)"):::frontend
        end
    end

    %% Content Management
    subgraph "Content Management"
        MarkdownContent("Markdown Content Files"):::content
        ContentImages("Image Assets"):::content
    end

    %% Markdoc Integration
    subgraph "Markdoc Integration"
        MarkdocClient("Markdoc Client"):::markdoc
        MarkdocServer("Markdoc Server"):::markdoc
        MarkdocTypes("Markdoc Types"):::markdoc
    end

    %% API Routes
    subgraph "API Routes"
        API("go-redirect-service API"):::api
    end

    %% Utility Modules
    subgraph "Utility Modules"
        FS("File System (fs)"):::utility
        Images("Image Handling"):::utility
        Mappings("Mappings Utilities"):::utility
        ScriptHandler("Script Handler"):::utility
        SourceQuery("Source Query Tracker"):::utility
    end

    %% Global Configuration and Build Tools
    subgraph "Configuration/Build"
        NextConfig("Next.js Config"):::config
        NextEnv("Next.js Environment"):::config
        Tsconfig("TypeScript Config"):::config
        TailwindConfig("Tailwind Config"):::config
        PostCSS("PostCSS Config"):::config
        Linting("Linting/Formatting"):::config
        LintingPrettier("Prettier Config"):::config
        Husky("Husky Pre-commit"):::config
    end

    %% External Services
    subgraph "External Services"
        Vercel("Vercel (Hosting)"):::external
        GitHub("GitHub (Version Control)"):::external
    end

    %% Connections between components
    NXPages -->|"uses"| Layout
    NXPages -->|"incorporates"| MarkdownPost
    NXPages -->|"incorporates"| Meta
    NXPages -->|"incorporates"| Post

    Layout -->|"includes"| Navbar
    Layout -->|"includes"| Footer
    Layout -->|"includes"| SkipToMain

    MarkdownContent -->|"input"| MarkdocServer
    MarkdocServer -->|"renders via"| MarkdocClient
    MarkdocClient -->|"feeds"| MarkdownPost
    MarkdocClient -->|"feeds"| Meta
    MarkdocClient -->|"feeds"| Post

    API -->|"supports"| NXPages

    FS -->|"supports"| MarkdocServer
    Images -->|"manages"| ContentImages

    Mappings -->|"assists"| NXPages
    ScriptHandler -->|"assists"| NXPages
    SourceQuery -->|"assists"| NXPages

    NextConfig -->|"deploys to"| Vercel
    TailwindConfig -->|"styles"| Layout
    TailwindConfig -->|"styles"| MarkdownPost
    PostCSS -->|"styles"| Layout
    PostCSS -->|"styles"| MarkdownPost
    Linting -->|"ensures quality for"| NXPages

    NXPages -->|"deployed on"| Vercel
    GitHub -->|"version controls"| NXPages

    %% Click Events for Frontend/UI Components
    click NXPages "https://github.com/jakub-studio/website/tree/main/src/pages"
    click Layout "https://github.com/jakub-studio/website/blob/main/src/components/Layout.tsx"
    click Navbar "https://github.com/jakub-studio/website/blob/main/src/components/Navbar.tsx"
    click Footer "https://github.com/jakub-studio/website/blob/main/src/components/Footer/index.tsx"
    click SkipToMain "https://github.com/jakub-studio/website/blob/main/src/components/SkipToMainContent.tsx"
    click MarkdownPost "https://github.com/jakub-studio/website/blob/main/src/components/MarkdownPost.tsx"
    click Meta "https://github.com/jakub-studio/website/blob/main/src/components/Meta.tsx"
    click Post "https://github.com/jakub-studio/website/blob/main/src/components/Post.tsx"
    click MDNodes "https://github.com/jakub-studio/website/tree/main/src/components/markdown"

    %% Click Events for Content Management
    click MarkdownContent "https://github.com/jakub-studio/website/tree/main/src/content"
    click ContentImages "https://github.com/jakub-studio/website/tree/main/src/content/_images"

    %% Click Events for Markdoc Integration
    click MarkdocClient "https://github.com/jakub-studio/website/tree/main/src/modules/markdown/client"
    click MarkdocServer "https://github.com/jakub-studio/website/tree/main/src/modules/markdown/server"
    click MarkdocTypes "https://github.com/jakub-studio/website/blob/main/src/modules/markdown/types.ts"

    %% Click Event for API Routes
    click API "https://github.com/jakub-studio/website/tree/main/src/pages/api/go-redirect-service"

    %% Click Events for Utility Modules
    click FS "https://github.com/jakub-studio/website/blob/main/src/modules/fs/index.ts"
    click Images "https://github.com/jakub-studio/website/tree/main/src/modules/images"
    click Mappings "https://github.com/jakub-studio/website/tree/main/src/modules/mappings"
    click ScriptHandler "https://github.com/jakub-studio/website/blob/main/src/modules/script-handler/index.tsx"
    click SourceQuery "https://github.com/jakub-studio/website/tree/main/src/modules/source-query-tracker"

    %% Click Events for Global Configuration and Build Tools
    click NextConfig "https://github.com/jakub-studio/website/blob/main/next.config.js"
    click NextEnv "https://github.com/jakub-studio/website/blob/main/next-env.d.ts"
    click Tsconfig "https://github.com/jakub-studio/website/blob/main/tsconfig.json"
    click TailwindConfig "https://github.com/jakub-studio/website/blob/main/tailwind.config.js"
    click PostCSS "https://github.com/jakub-studio/website/blob/main/postcss.config.js"
    click Linting "https://github.com/jakub-studio/website/blob/main/.eslintrc.json"
    click LintingPrettier "https://github.com/jakub-studio/website/blob/main/.prettierrc.json"
    click Husky "https://github.com/jakub-studio/website/tree/main/.husky/pre-commit"

    %% Click Events for External Services
    click Vercel "https://github.com/jakub-studio/website/tree/main/Vercel"
    click GitHub "https://github.com/jakub-studio/website/tree/main/GitHub"

    %% Class Definitions for Colors
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#004085;
    classDef content fill:#d4edda,stroke:#155724,stroke-width:2px,color:#155724;
    classDef markdoc fill:#e2d6f7,stroke:#6f42c1,stroke-width:2px,color:#6f42c1;
    classDef api fill:#f8d7da,stroke:#721c24,stroke-width:2px,color:#721c24;
    classDef utility fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#856404;
    classDef config fill:#d1ecf1,stroke:#0c5460,stroke-width:2px,color:#0c5460;
    classDef external fill:#fde2e4,stroke:#c92a2a,stroke-width:2px,color:#c92a2a;
```
