# stats-organization/github-stats-extended architecture

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

- Interactive diagram: https://gitdiagram.com/stats-organization/github-stats-extended
- Repository: https://github.com/stats-organization/github-stats-extended
- Video tour (about a minute): https://gitdiagram.com/stats-organization/github-stats-extended/video

## Overview

GitHub Stats Extended generates customizable GitHub, language, repository, gist, and WakaTime SVG cards. The principal workflow begins with a README image request, passes through the backend router, validates and authorizes parameters, fetches external data, renders a themed card, and returns SVG. The frontend wizard provides a visual configuration path that produces equivalent API URLs. Authentication and request persistence support private access, rate management, and recent-request handling. Unsampled modules are represented only where their paths and documented responsibilities are clear.

Main entry points: [`apps/backend/router.js`](https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/router.js) (API Router), [`packages/core/src/api/index.js`](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/index.js) (Stats API), [`packages/core/src/api/gist.ts`](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/gist.ts) (Gist API), [`packages/core/src/api/pin.js`](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/pin.js) (Pin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend Gateway"]
  node_backend_router["API Router<br/>[router.js]"]
  node_cache_control["Cache Control<br/>[cache.js]"]
  node_access_guard["Access Guard<br/>[access.js]"]
end

subgraph group_core["Card Generation"]
  node_stats_api["Stats API<br/>[index.js]"]
  node_gist_api["Gist API<br/>[gist.ts]"]
  node_pin_api["Pin API<br/>[pin.js]"]
  node_languages_api["Languages API<br/>[top-langs.js]"]
  node_wakatime_api["WakaTime API<br/>[wakatime.js]"]
  node_stats_fetcher["Stats Fetcher<br/>[stats.ts]"]
  node_gist_fetcher["Gist Fetcher<br/>[gist.ts]"]
  node_repo_fetcher["Repository Fetcher<br/>[repo.ts]"]
  node_languages_fetcher["Languages Fetcher<br/>[top-languages.ts]"]
  node_wakatime_fetcher["WakaTime Fetcher<br/>[wakatime.ts]"]
  node_stats_card["Stats Renderer<br/>[stats.ts]"]
  node_languages_card["Languages Renderer<br/>[top-languages.ts]"]
  node_repo_card["Repository Renderer<br/>[repo.ts]"]
  node_gist_card["Gist Renderer<br/>[gist.ts]"]
  node_wakatime_card["WakaTime Renderer<br/>[wakatime.ts]"]
end

subgraph group_frontend["Wizard UI"]
  node_wizard["Card Wizard<br/>[Wizard.tsx]"]
  node_wizard_home["Wizard Home<br/>[Home.tsx]"]
  node_card_url["Card URL Builder<br/>[buildCardUrl.ts]"]
  node_card_display["Card Display<br/>[Display.tsx]"]
end

subgraph group_account["Accounts and Persistence"]
  node_account_auth["Authentication<br/>[authenticate.js]"]
  node_user_service["User Accounts<br/>[users.js]"]
  node_request_store["Request Database<br/>[database.js]"]
end

node_readme_user(("README Visitor"))
node_github_api{{"GitHub API"}}
node_wakatime_service{{"WakaTime API"}}
node_postgres[("PostgreSQL")]
node_svg_card["SVG Card"]

node_readme_user -->|"requests card"| node_backend_router
node_wizard -->|"opens wizard"| node_wizard_home
node_wizard_home -->|"builds URL"| node_card_url
node_card_url -->|"targets API"| node_backend_router
node_wizard_home -->|"shows preview"| node_card_display
node_backend_router -->|"checks access"| node_access_guard
node_backend_router -->|"sets caching"| node_cache_control
node_backend_router -->|"dispatches stats"| node_stats_api
node_backend_router -->|"dispatches gist"| node_gist_api
node_backend_router -->|"dispatches pin"| node_pin_api
node_backend_router -->|"dispatches languages"| node_languages_api
node_backend_router -->|"dispatches WakaTime"| node_wakatime_api
node_stats_api -->|"fetches stats"| node_stats_fetcher
node_stats_api -->|"renders stats"| node_stats_card
node_gist_api -->|"fetches gist"| node_gist_fetcher
node_gist_api -->|"renders gist"| node_gist_card
node_pin_api -->|"fetches repository"| node_repo_fetcher
node_pin_api -->|"renders repository"| node_repo_card
node_languages_api -->|"fetches languages"| node_languages_fetcher
node_languages_api -->|"renders languages"| node_languages_card
node_wakatime_api -->|"fetches time"| node_wakatime_fetcher
node_wakatime_api -->|"renders time"| node_wakatime_card
node_stats_fetcher -->|"queries GitHub"| node_github_api
node_gist_fetcher -->|"queries GitHub"| node_github_api
node_repo_fetcher -->|"queries GitHub"| node_github_api
node_languages_fetcher -->|"queries GitHub"| node_github_api
node_wakatime_fetcher -.->|"queries WakaTime"| node_wakatime_service
node_stats_card -->|"produces SVG"| node_svg_card
node_languages_card -->|"produces SVG"| node_svg_card
node_repo_card -->|"produces SVG"| node_svg_card
node_gist_card -->|"produces SVG"| node_svg_card
node_wakatime_card -->|"produces SVG"| node_svg_card
node_backend_router -->|"stores request"| node_request_store
node_account_auth -->|"authenticates user"| node_user_service
node_user_service -->|"stores access"| node_request_store
node_backend_router -->|"dispatches auth"| node_account_auth
node_request_store -->|"reads and writes"| node_postgres
node_account_auth -->|"returns result"| node_svg_card

click node_backend_router "https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/router.js"
click node_cache_control "https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/src/common/cache.js"
click node_access_guard "https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/src/common/access.js"
click node_stats_api "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/index.js"
click node_gist_api "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/gist.ts"
click node_pin_api "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/pin.js"
click node_languages_api "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/top-langs.js"
click node_wakatime_api "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/wakatime.js"
click node_stats_fetcher "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/fetchers/stats.ts"
click node_gist_fetcher "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/fetchers/gist.ts"
click node_repo_fetcher "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/fetchers/repo.ts"
click node_languages_fetcher "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/fetchers/top-languages.ts"
click node_wakatime_fetcher "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/fetchers/wakatime.ts"
click node_stats_card "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/cards/stats.ts"
click node_languages_card "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/cards/top-languages.ts"
click node_repo_card "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/cards/repo.ts"
click node_gist_card "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/cards/gist.ts"
click node_wakatime_card "https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/cards/wakatime.ts"
click node_wizard "https://github.com/stats-organization/github-stats-extended/blob/master/apps/frontend/src/wizard/Wizard.tsx"
click node_wizard_home "https://github.com/stats-organization/github-stats-extended/blob/master/apps/frontend/src/wizard/Home/Home.tsx"
click node_card_url "https://github.com/stats-organization/github-stats-extended/blob/master/apps/frontend/src/wizard/Home/buildCardUrl.ts"
click node_card_display "https://github.com/stats-organization/github-stats-extended/blob/master/apps/frontend/src/wizard/Home/stages/Display.tsx"
click node_account_auth "https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/api-renamed/authenticate.js"
click node_user_service "https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/src/users.js"
click node_request_store "https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/src/common/database.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_router,node_cache_control,node_access_guard toneBlue
class node_stats_api,node_gist_api,node_pin_api,node_languages_api,node_wakatime_api,node_stats_fetcher,node_gist_fetcher,node_repo_fetcher,node_languages_fetcher,node_wakatime_fetcher,node_stats_card,node_languages_card,node_repo_card,node_gist_card,node_wakatime_card,node_postgres toneAmber
class node_wizard,node_wizard_home,node_card_url,node_card_display,node_github_api,node_wakatime_service toneMint
class node_account_auth,node_user_service,node_request_store toneRose
class node_readme_user,node_svg_card toneIndigo
```

## Components

### Backend Gateway

- [API Router](https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/router.js): `apps/backend/router.js`
- [Cache Control](https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/src/common/cache.js): `apps/backend/src/common/cache.js`
- [Access Guard](https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/src/common/access.js): `apps/backend/src/common/access.js`

### Card Generation

- [Stats API](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/index.js): `packages/core/src/api/index.js`
- [Gist API](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/gist.ts): `packages/core/src/api/gist.ts`
- [Pin API](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/pin.js): `packages/core/src/api/pin.js`
- [Languages API](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/top-langs.js): `packages/core/src/api/top-langs.js`
- [WakaTime API](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/api/wakatime.js): `packages/core/src/api/wakatime.js`
- [Stats Fetcher](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/fetchers/stats.ts): `packages/core/src/fetchers/stats.ts`
- [Gist Fetcher](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/fetchers/gist.ts): `packages/core/src/fetchers/gist.ts`
- [Repository Fetcher](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/fetchers/repo.ts): `packages/core/src/fetchers/repo.ts`
- [Languages Fetcher](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/fetchers/top-languages.ts): `packages/core/src/fetchers/top-languages.ts`
- [WakaTime Fetcher](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/fetchers/wakatime.ts): `packages/core/src/fetchers/wakatime.ts`
- [Stats Renderer](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/cards/stats.ts): `packages/core/src/cards/stats.ts`
- [Languages Renderer](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/cards/top-languages.ts): `packages/core/src/cards/top-languages.ts`
- [Repository Renderer](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/cards/repo.ts): `packages/core/src/cards/repo.ts`
- [Gist Renderer](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/cards/gist.ts): `packages/core/src/cards/gist.ts`
- [WakaTime Renderer](https://github.com/stats-organization/github-stats-extended/blob/master/packages/core/src/cards/wakatime.ts): `packages/core/src/cards/wakatime.ts`

### Wizard UI

- [Card Wizard](https://github.com/stats-organization/github-stats-extended/blob/master/apps/frontend/src/wizard/Wizard.tsx): `apps/frontend/src/wizard/Wizard.tsx`
- [Wizard Home](https://github.com/stats-organization/github-stats-extended/blob/master/apps/frontend/src/wizard/Home/Home.tsx): `apps/frontend/src/wizard/Home/Home.tsx`
- [Card URL Builder](https://github.com/stats-organization/github-stats-extended/blob/master/apps/frontend/src/wizard/Home/buildCardUrl.ts): `apps/frontend/src/wizard/Home/buildCardUrl.ts`
- [Card Display](https://github.com/stats-organization/github-stats-extended/blob/master/apps/frontend/src/wizard/Home/stages/Display.tsx): `apps/frontend/src/wizard/Home/stages/Display.tsx`

### Accounts and Persistence

- [Authentication](https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/api-renamed/authenticate.js): `apps/backend/api-renamed/authenticate.js`
- [User Accounts](https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/src/users.js): `apps/backend/src/users.js`
- [Request Database](https://github.com/stats-organization/github-stats-extended/blob/master/apps/backend/src/common/database.js): `apps/backend/src/common/database.js`

### Other components

- **README Visitor**
- **GitHub API**
- **WakaTime API**
- **PostgreSQL**
- **SVG Card**

## Connections

- README Visitor → API Router: requests card
- Card Wizard → Wizard Home: opens wizard
- Wizard Home → Card URL Builder: builds URL
- Card URL Builder → API Router: targets API
- Wizard Home → Card Display: shows preview
- API Router → Access Guard: checks access
- API Router → Cache Control: sets caching
- API Router → Stats API: dispatches stats
- API Router → Gist API: dispatches gist
- API Router → Pin API: dispatches pin
- API Router → Languages API: dispatches languages
- API Router → WakaTime API: dispatches WakaTime
- Stats API → Stats Fetcher: fetches stats
- Stats API → Stats Renderer: renders stats
- Gist API → Gist Fetcher: fetches gist
- Gist API → Gist Renderer: renders gist
- Pin API → Repository Fetcher: fetches repository
- Pin API → Repository Renderer: renders repository
- Languages API → Languages Fetcher: fetches languages
- Languages API → Languages Renderer: renders languages
- WakaTime API → WakaTime Fetcher: fetches time
- WakaTime API → WakaTime Renderer: renders time
- Stats Fetcher → GitHub API: queries GitHub
- Gist Fetcher → GitHub API: queries GitHub
- Repository Fetcher → GitHub API: queries GitHub
- Languages Fetcher → GitHub API: queries GitHub
- WakaTime Fetcher → WakaTime API: queries WakaTime
- Stats Renderer → SVG Card: produces SVG
- Languages Renderer → SVG Card: produces SVG
- Repository Renderer → SVG Card: produces SVG
- Gist Renderer → SVG Card: produces SVG
- WakaTime Renderer → SVG Card: produces SVG
- API Router → Request Database: stores request
- Authentication → User Accounts: authenticates user
- User Accounts → Request Database: stores access
- API Router → Authentication: dispatches auth
- Request Database → PostgreSQL: reads and writes
- Authentication → SVG Card: returns result
