# toss/frontend-fundamentals architecture

> Architecture diagram of the GitHub repository toss/frontend-fundamentals, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/toss/frontend-fundamentals
- Repository: https://github.com/toss/frontend-fundamentals

## Overview

##### Project Type and Purpose
- This is a static documentation site (“Frontend Fundamentals”) built with VitePress. Its goal is to provide guidelines and best practices for frontend developers (bundling, code quality, etc.). Users browse a statically generated site; contributors submit via GitHub Discussions.

##### Main Components
a. Content Layer
- Markdown files under​ `fundamentals/bundling` and `fundamentals/code-quality` (and localized versions)
- Assets under `public/` and `images/`
b. Theme & Presentation Layer
- Custom Vue components and styles in `.vitepress/theme/` directories
- Composables/hooks under `.vitepress/theme/hooks`
c. Build & Dev Tooling
- VitePress (configured in `.vitepress/config.mts`)
- Yarn v4 with Plug’n’Play (`.yarn/`, `.yarnrc.yml`)
- TypeScript config (`tsconfig.json`) and Prettier (`.prettierrc`)
d. API Integration
- `api/github.js` for GitHub Discussions calls (Giscus comment integration)
e. CI/CD & Hosting
- GitHub repository with PR/discussion templates (`.github/`)
- Deployed to Vercel (via `vercel.json`) as a fully static site

##### Component Relationships & Data Flow
- Developer → GitHub (pushes code, opens PR)
- GitHub Actions or Vercel Hook → Yarn install & `vitepress build`
- Build output (static HTML/CSS/JS) → Vercel CDN
- Browser ←– HTTP GET to Vercel CDN → static site
- Static site (Vue) loads, then Giscus widget uses `api/github.js` to fetch/post comments to GitHub Discussions
- Local dev: `yarn dev` → VitePress dev server with HMR

##### Architectural Patterns & Design Principles
- Static Site Generation (SSG) for performance and simplicity
- Component-based theming using Vue for layout, navigation, comments
- Markdown-as-source-of-truth for content, with multi-language support
- Yarn Plug’n’Play for fast, deterministic installs
- Separation of concerns: content vs. theme vs. build scripts vs. deployment config

##### Essential Details to Capture
- Markdown content directories and localization structure
- `.vitepress` theme overrides and custom hooks
- Yarn PnP setup and lockfile integrity
- API script role in enabling comments/discussion integration
- Vercel configuration for static deployment
- How changes propagate from commit → build → live site

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Content Layer"
        MD1["Markdown: fundamentals/bundling/**"]:::content
        MD2["Markdown: fundamentals/code-quality/**"]:::content
        Assets1["Assets: images/"]:::content
        Assets2["Assets: public/"]:::content
    end

    subgraph "Theme & Presentation"
        ThemeBund["Bundling Theme (.vitepress/theme)"]:::theme
        CommentsVue["Comments.vue"]:::theme
        HooksBund["hooks"]:::theme
        ConfigBund["config.mts"]:::theme

        ThemeCode["Code-Quality Theme (.vitepress/theme)"]:::theme
        GHDiscVue["GithubDiscussions.vue"]:::theme
        UseApiTS["useGithubApi.ts"]:::theme
        UseGiscus["useGiscusTheme.tsx"]:::theme
        ConfigCode["config.mts"]:::theme
    end

    subgraph "Build & Dev Tooling"
        YarnDir[".yarn/"]:::build
        YarnRC[".yarnrc.yml"]:::build
        PNPCJS[".pnp.cjs"]:::build
        PNPLOADER[".pnp.loader.mjs"]:::build
        Prettierrc[".prettierrc"]:::build
        TSRoot["tsconfig.json"]:::build
        TSBund["fundamentals/bundling/tsconfig.json"]:::build
        TSCode["fundamentals/code-quality/tsconfig.json"]:::build

        ConfigViteBund[".vitepress/config.mts"]:::build
        ConfigViteCode[".vitepress/config.mts"]:::build
    end

    subgraph "API Integration"
        APIWrapper["api/github.js"]:::build
        GitHubAPI[(GitHub Discussions API / Giscus)]:::external
    end

    subgraph "Local Development"
        Developer((Developer)):::dev
        YarnDev["yarn dev (VitePress Dev Server)"]:::dev
        VitePressDev["VitePress Dev Server"]:::build
        BrowserDev["Browser (HMR)"]:::runtime
    end

    subgraph "CI/CD Pipeline"
        GitHubRepo[(GitHub Repo)]:::external
        GitHubActions["GitHub Actions / Vercel Hook"]:::build
        Install["Yarn install (PnP)"]:::build
        BuildCmd["vitepress build"]:::build
    end

    subgraph "Production Runtime"
        Vercel["Vercel Platform"]:::cloud
        CDN["Vercel CDN (Static Assets)"]:::cloud
        Browser["Browser"]:::runtime
    end

    subgraph "CI/CD Config"
        GitHubDir[".github/"]:::build
        VercelJSON["vercel.json"]:::build
    end

    %% Relationships
    MD1 --> VitePressDev
    MD2 --> VitePressDev
    Assets1 --> VitePressDev
    Assets2 --> VitePressDev
    ThemeBund --> VitePressDev
    CommentsVue --> VitePressDev
    HooksBund --> VitePressDev
    ConfigBund --> VitePressDev
    ThemeCode --> VitePressDev
    GHDiscVue --> VitePressDev
    UseApiTS --> VitePressDev
    UseGiscus --> VitePressDev
    ConfigCode --> VitePressDev

    VitePressDev --> BrowserDev

    Developer --> YarnDev
    YarnDev --> VitePressDev

    Developer -->|push/PR| GitHubRepo
    GitHubRepo --> GitHubActions
    GitHubActions --> Install
    Install --> BuildCmd
    BuildCmd --> Vercel

    GitHubDir --> GitHubRepo
    VercelJSON --> Vercel

    Vercel --> CDN
    Browser --> CDN
    CDN --> Browser

    Browser -->|Giscus widget API calls| GitHubAPI
    APIWrapper --> GitHubAPI
    BrowserDev -->|Giscus widget API calls| GitHubAPI

    %% Click Events
    click MD1 "https://github.com/toss/frontend-fundamentals/tree/main/fundamentals/bundling/**"
    click MD2 "https://github.com/toss/frontend-fundamentals/tree/main/fundamentals/code-quality/**"
    click Assets1 "https://github.com/toss/frontend-fundamentals/tree/main/images/"
    click Assets2 "https://github.com/toss/frontend-fundamentals/tree/main/public/"
    click ThemeBund "https://github.com/toss/frontend-fundamentals/tree/main/fundamentals/bundling/.vitepress/theme/"
    click CommentsVue "https://github.com/toss/frontend-fundamentals/blob/main/fundamentals/bundling/.vitepress/theme/components/Comments.vue"
    click HooksBund "https://github.com/toss/frontend-fundamentals/tree/main/fundamentals/bundling/.vitepress/theme/hooks/"
    click ConfigBund "https://github.com/toss/frontend-fundamentals/blob/main/fundamentals/bundling/.vitepress/config.mts"
    click ThemeCode "https://github.com/toss/frontend-fundamentals/tree/main/fundamentals/code-quality/.vitepress/theme/"
    click GHDiscVue "https://github.com/toss/frontend-fundamentals/blob/main/fundamentals/code-quality/.vitepress/theme/components/GithubDiscussions.vue"
    click UseApiTS "https://github.com/toss/frontend-fundamentals/blob/main/fundamentals/code-quality/.vitepress/theme/composables/useGithubApi.ts"
    click UseGiscus "https://github.com/toss/frontend-fundamentals/blob/main/fundamentals/code-quality/.vitepress/theme/hooks/useGiscusTheme.tsx"
    click ConfigCode "https://github.com/toss/frontend-fundamentals/blob/main/fundamentals/code-quality/.vitepress/config.mts"
    click YarnDir "https://github.com/toss/frontend-fundamentals/tree/main/.yarn/"
    click YarnRC "https://github.com/toss/frontend-fundamentals/blob/main/.yarnrc.yml"
    click PNPCJS "https://github.com/toss/frontend-fundamentals/blob/main/.pnp.cjs"
    click PNPLOADER "https://github.com/toss/frontend-fundamentals/blob/main/.pnp.loader.mjs"
    click Prettierrc "https://github.com/toss/frontend-fundamentals/blob/main/.prettierrc"
    click TSRoot "https://github.com/toss/frontend-fundamentals/blob/main/tsconfig.json"
    click TSBund "https://github.com/toss/frontend-fundamentals/blob/main/fundamentals/bundling/tsconfig.json"
    click TSCode "https://github.com/toss/frontend-fundamentals/blob/main/fundamentals/code-quality/tsconfig.json"
    click APIWrapper "https://github.com/toss/frontend-fundamentals/blob/main/api/github.js"
    click GitHubDir "https://github.com/toss/frontend-fundamentals/tree/main/.github/"
    click VercelJSON "https://github.com/toss/frontend-fundamentals/blob/main/vercel.json"

    %% Styles
    classDef dev fill:#e0f7e9,stroke:#2f7a5a,color:#0b3d2e
    classDef build fill:#d0e7ff,stroke:#1e4f91,color:#102b56
    classDef theme fill:#cfe8fc,stroke:#1a5a8a,color:#0e364f
    classDef content fill:#e8f0fd,stroke:#1e3f8a,color:#081d3c
    classDef cloud fill:#ffe5b4,stroke:#b87e00,color:#653f00
    classDef runtime fill:#f0f0f0,stroke:#666666,color:#333333
    classDef external fill:#f2f2f2,stroke:#888888,color:#444444
```
