# bangumi/frontend architecture

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

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

## Overview

##### File-Structure Analysis & Architectural Patterns
- Top-level configuration:
- `pnpm-workspace.yaml`, `package.json`, `tsconfig.json` – define the monorepo.
- GitHub Actions & Husky hooks – CI/CD pipelines for lint, test, build, release.
- Internal packages under `packages/`:
- `design` – UI component library (Storybook, theming).
- `client` – code-generated SDK from `api.yaml`.
- `utils` – shared helper functions (BBCode parser, wiki syntax, pages).
- `server` – placeholder for standalone server logic or Node modules.
- `website` – the main React/Vite web app with routes, mocks, E2E tests.
- `_functions/p1` – serverless functions (e.g., Vercel/Netlify lambda) for API proxies or backend logic.
- Testing frameworks: Vitest for unit, Playwright for e2e, Storybook for visual testing.

##### Key Architectural Patterns
- Monorepo with PNPM workspace: enforces strict versioning and local linking between packages.
- Serverless microservices: `_functions/p1` acts as backend handlers.
- CI/CD via GitHub Actions: separate workflows for lint, unit, e2e, Storybook build, release.

##### Components
a. Developer & CI/CD
- Local Developer Workstation (pnpm, VSCode, Git)
- GitHub Actions CI/CD
b. Monorepo Controller
- PNPM Workspace & Shared Config
c. Internal Package Modules
- Design System (`packages/design`)
- OpenAPI Client SDK (`packages/client`)
- Utility Library (`packages/utils`)
- Server-side Package (`packages/server`)
- Website App (`packages/website`)
d. Serverless Functions
- `_functions/p1` handlers
e. External Dependencies
- Third-party APIs (Bangumi API)
- NPM Registry (for package publishes)
f. Testing & Deployment
- Storybook Service
- Playwright E2E environment
- Vercel/Netlify (or target hosting)

##### Relationships & Data Flows
- Developer → checks out repo → installs via PNPM → edits any package.
- Client SDK makes HTTP calls to serverless functions or external APIs.
- Serverless functions may use `packages/server` or `packages/utils` for shared logic.
- CI/CD pipelines run lint/test on all packages → build storybook → publish updated packages → deploy website & functions.
- Website (browser) ↔ Serverless functions (API) ↔ External Bangumi backend.

##### Essential Callouts
- Monorepo’s dependency graph at the package level.
- Both local developer workflows and automated CI/CD processes.
- Detail the runtime interactions between browser, serverless endpoints, and external APIs.
- Major technologies: React, Vite, TypeScript, Storybook, PNPM, Vitest, Playwright, GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Participants
    Developer["Developer Workstation\n(pnpm, VSCode, Git)"]:::gray
    PNPM["PNPM Workspace & Shared Config"]:::green
    Vitest["Vitest Unit Test Config"]:::green

    subgraph "CI/CD"
        GH["GitHub Actions CI/CD"]:::green
        Husky["Husky Hooks (pre-commit)"]:::green
    end

    subgraph "Monorepo"
        subgraph "packages"
            Design["Design System"]:::blue
            SB["Storybook Config"]:::blue
            Icons["Icons Library"]:::blue
            Client["OpenAPI Client SDK"]:::blue
            Utils["Utility Library"]:::blue
            ServerPkg["Server-side Package"]:::blue
            Website["Website App"]:::blue
            ViteCfg["vite.config.ts"]:::blue
            PWCfg["playwright.config.ts"]:::blue
            E2E["E2E Tests"]:::blue
        end
        subgraph "_functions"
            Fn["Serverless Functions"]:::blue
        end
    end

    subgraph "Testing & Deployment"
        StorybookSvc["Storybook Service"]:::orange
        PlaywrightEnv["Playwright E2E Environment"]:::orange
    end

    subgraph "External"
        BangumiAPI["Bangumi External API"]:::orange
        Hosting["Hosting (Vercel/Netlify)"]:::orange
    end

    NPMReg["NPM Registry"]:::green

    %% Relationships
    Developer --> PNPM
    Developer --> Husky
    Developer --> Vitest

    PNPM --> Design
    PNPM --> Icons
    PNPM --> Client
    PNPM --> Utils
    PNPM --> ServerPkg
    PNPM --> Website
    PNPM --> Fn

    Website -->|"imports"| Design
    Website -->|"imports"| Icons
    Website -->|"imports"| Utils
    Website -->|"imports"| Client
    Website --> Hosting

    Website <-->|"runtime API"| Fn
    Client -->|"calls"| Fn
    Client -->|"calls"| BangumiAPI
    Fn -->|"uses"| Utils
    Fn -->|"uses"| ServerPkg

    GH -->|"runs lint/test/build"| Vitest
    GH -->|"builds"| StorybookSvc
    GH -->|"publishes"| NPMReg
    GH -->|"deploys"| Hosting

    %% Click Events
    click GH "https://github.com/bangumi/frontend/tree/master/.github/workflows/"
    click Husky "https://github.com/bangumi/frontend/tree/master/.husky/pre-commit"
    click PNPM "https://github.com/bangumi/frontend/blob/master/pnpm-workspace.yaml"
    click PNPM "https://github.com/bangumi/frontend/blob/master/package.json"
    click PNPM "https://github.com/bangumi/frontend/blob/master/tsconfig.json"
    click Design "https://github.com/bangumi/frontend/tree/master/packages/design/"
    click SB "https://github.com/bangumi/frontend/tree/master/packages/design/.storybook/"
    click Icons "https://github.com/bangumi/frontend/tree/master/packages/icons/"
    click Client "https://github.com/bangumi/frontend/blob/master/packages/client/api.yaml"
    click Client "https://github.com/bangumi/frontend/blob/master/packages/client/index.ts"
    click Client "https://github.com/bangumi/frontend/blob/master/packages/client/client.ts"
    click Client "https://github.com/bangumi/frontend/blob/master/packages/client/scripts/update-openapi.mjs"
    click Utils "https://github.com/bangumi/frontend/tree/master/packages/utils/"
    click ServerPkg "https://github.com/bangumi/frontend/tree/master/packages/server/"
    click Website "https://github.com/bangumi/frontend/tree/master/packages/website/"
    click ViteCfg "https://github.com/bangumi/frontend/blob/master/packages/website/vite.config.ts"
    click PWCfg "https://github.com/bangumi/frontend/blob/master/packages/website/playwright.config.ts"
    click E2E "https://github.com/bangumi/frontend/tree/master/packages/website/e2e/"
    click Fn "https://github.com/bangumi/frontend/blob/master/_functions/p1/[[catchall]].js"
    click Vitest "https://github.com/bangumi/frontend/blob/master/vitest.config.ts"

    %% Styles
    classDef blue fill:#CCF,stroke:#33A,stroke-width:2px
    classDef green fill:#CFC,stroke:#0A0,stroke-width:2px
    classDef orange fill:#FDD,stroke:#F60,stroke-width:2px
    classDef gray fill:#EEE,stroke:#888,stroke-width:2px
```
