# yukionishi1129/github-readme-stats architecture

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

- Interactive diagram: https://gitdiagram.com/yukionishi1129/github-readme-stats
- Repository: https://github.com/yukionishi1129/github-readme-stats

## Overview

##### Project Type and Purpose
- This is an open-source, serverless Node.js “card generator” service that produces dynamic SVG badges for GitHub READMEs.
- It exposes HTTP endpoints (api/, index.js) to generate stats cards, repo pins, top-languages cards, and WakaTime cards.

##### File Structure Analysis
- Top-level “api” folder: HTTP request handlers (pin.js, top-langs.js, wakatime.js, index.js).
- “src” folder: core business logic modules, organized into subfolders:
- fetchers/ – modules that call external APIs (GitHub, WakaTime).
- cards/ – modules that assemble SVG nodes for each card type.
- calculateRank.js – ranking algorithm.
- getStyles.js, translations.js – styling and localization.
- “themes” folder: JSON-based theme definitions.
- “scripts” folder: CLI utilities for documentation generation, theme previews, cleanup.
- “tests” & Jest config – unit, integration, e2e tests.
- CI/CD config: GitHub Actions workflows, husky pre-commit, vercel.json for Vercel deployment.
- “docs” – localized README variants.

##### Key README Insights
- Service endpoints under `/api` path generate SVGs based on query params.
- Heavy use of caching (cache_seconds header) to minimize GitHub API rate-limit impact.
- Supports multiple card types, theming, customization via URL parameters.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Zones
    subgraph "Client & CDN"
        Client["GitHub README (Markdown)"]:::client
        CDN["CDN Cache"]:::cache
    end

    subgraph "Serverless Compute"
        Router["API Router\n(api/index.js)"]:::blue
        Pin["Pin Endpoint\n(api/pin.js)"]:::blue
        TopLangs["Top Languages Endpoint\n(api/top-langs.js)"]:::blue
        Waka["WakaTime Endpoint\n(api/wakatime.js)"]:::blue

        subgraph "Fetchers"
            RepoF["GitHub Repo Fetcher\n(src/fetchers/repo-fetcher.js)"]:::green
            StatsF["GitHub Stats Fetcher\n(src/fetchers/stats-fetcher.js)"]:::green
            TopLF["Top Languages Fetcher\n(src/fetchers/top-languages-fetcher.js)"]:::green
            WakaF["WakaTime Fetcher\n(src/fetchers/wakatime-fetcher.js)"]:::green
        end

        subgraph "Business Logic"
            Rank["Ranking Algorithm\n(src/calculateRank.js)"]:::green
            Utils["Utilities\n(src/common/utils.js)"]:::green
            Retry["Retry Logic\n(src/common/retryer.js)"]:::green
        end

        subgraph "Theme Engine"
            Themes["Theme Definitions\n(themes/index.js)"]:::green
            Styles["Style Resolver\n(src/getStyles.js)"]:::green
        end

        subgraph "Card Generators"
            Cards["Central Export\n(src/cards/index.js)"]:::green
            RepoCard["Repository Pin Card\n(src/cards/repo-card.js)"]:::green
            StatsCard["Stats Card\n(src/cards/stats-card.js)"]:::green
            TLCard["Top Languages Card\n(src/cards/top-languages-card.js)"]:::green
            WakaCard["WakaTime Card\n(src/cards/wakatime-card.js)"]:::green
        end
    end

    subgraph "External Services"
        GHAPI["GitHub API"]:::external
        WakaAPI["WakaTime API"]:::external
    end

    subgraph "CI/CD Pipelines"
        Commit["Code Commit"]:::orange
        Actions["GitHub Actions\n(.github/workflows/*.yml)"]:::orange
        Husky["Pre-commit Hooks\n(.husky/pre-commit)"]:::orange
        JestCfg["Jest Configuration\n(jest.config.js,\njest.e2e.config.js)"]:::orange
        Scripts["Scripts\n(scripts)"]:::orange
        Deploy["Auto-deploy\n(Vercel)"]:::orange
    end

    %% Request Flow
    Client -->|"HTTP image request"| CDN
    CDN -->|"cache miss"| Router
    Router -->|"route to pin"| Pin
    Router -->|"route to top-langs"| TopLangs
    Router -->|"route to wakatime"| Waka

    %% Fetchers to APIs
    Pin -->|"invoke fetchers"| RepoF
    TopLangs -->|"invoke fetchers"| TopLF
    Waka -->|"invoke fetchers"| WakaF

    RepoF -->|"HTTP/JSON"| GHAPI
    StatsF -->|"HTTP/JSON"| GHAPI
    TopLF -->|"HTTP/JSON"| GHAPI
    WakaF -->|"HTTP/JSON"| WakaAPI

    %% Fetchers to Logic
    RepoF --> Rank
    StatsF --> Rank
    TopLF --> Rank
    WakaF --> Rank

    Rank --> Utils
    Rank --> Retry

    %% Logic & Theme to Card Generators
    Rank --> Cards
    Utils --> Cards
    Retry --> Cards
    Themes --> Styles
    Styles --> Cards

    Cards --> RepoCard
    Cards --> StatsCard
    Cards --> TLCard
    Cards --> WakaCard

    RepoCard --> Router
    StatsCard --> Router
    TLCard --> Router
    WakaCard --> Router

    Router -->|"SVG Response"| CDN
    CDN -->|"serve cached SVG"| Client

    %% CI/CD Flow
    Commit --> Actions
    Commit --> Husky
    Commit --> JestCfg
    Commit --> Scripts
    Actions --> Deploy
    Husky --> Deploy
    JestCfg --> Deploy
    Scripts --> Deploy

    %% Styles
    classDef blue fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef green fill:#E6FFED,stroke:#28A745,color:#28A745
    classDef orange fill:#FFF5E6,stroke:#D15704,color:#D15704
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D
    classDef client,cache blue
    class Router,Pin,TopLangs,Waka blue
    class RepoF,StatsF,TopLF,WakaF,Rank,Utils,Retry,Themes,Styles,Cards,RepoCard,StatsCard,TLCard,WakaCard green
    class GHAPI,WakaAPI external
    class Commit,Actions,Husky,JestCfg,Scripts,Deploy orange

    %% Click Events
    click Router "https://github.com/yukionishi1129/github-readme-stats/blob/master/api/index.js"
    click Pin "https://github.com/yukionishi1129/github-readme-stats/blob/master/api/pin.js"
    click TopLangs "https://github.com/yukionishi1129/github-readme-stats/blob/master/api/top-langs.js"
    click Waka "https://github.com/yukionishi1129/github-readme-stats/blob/master/api/wakatime.js"
    click RepoF "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/fetchers/repo-fetcher.js"
    click StatsF "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/fetchers/stats-fetcher.js"
    click TopLF "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/fetchers/top-languages-fetcher.js"
    click WakaF "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/fetchers/wakatime-fetcher.js"
    click Rank "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/calculateRank.js"
    click Utils "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/common/utils.js"
    click Retry "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/common/retryer.js"
    click Themes "https://github.com/yukionishi1129/github-readme-stats/blob/master/themes/index.js"
    click Styles "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/getStyles.js"
    click Cards "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/cards/index.js"
    click RepoCard "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/cards/repo-card.js"
    click StatsCard "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/cards/stats-card.js"
    click TLCard "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/cards/top-languages-card.js"
    click WakaCard "https://github.com/yukionishi1129/github-readme-stats/blob/master/src/cards/wakatime-card.js"
    click Actions "https://github.com/yukionishi1129/github-readme-stats/blob/master/.github/workflows/*.yml"
    click Husky "https://github.com/yukionishi1129/github-readme-stats/tree/master/.husky/pre-commit"
    click JestCfg "https://github.com/yukionishi1129/github-readme-stats/blob/master/jest.config.js"
    click Scripts "https://github.com/yukionishi1129/github-readme-stats/tree/master/scripts"
```
