# bennettschwartz/githubcommitsleaderboard architecture

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

- Interactive diagram: https://gitdiagram.com/bennettschwartz/githubcommitsleaderboard
- Repository: https://github.com/bennettschwartz/githubcommitsleaderboard

## Overview

1. **Overall shape**
   - This is a Next.js App Router application deployed for **Cloudflare Workers** with a PostgreSQL backend on **Neon**.
   - The repo is split into three clear layers: UI pages/components, server API routes, and shared server-side domain logic in `src/lib`.

2. **User-facing UI**
   - The main site lives under `src/app/` and includes:
     - the public leaderboard homepage
     - user profile pages under `/u/[login]`
     - compare pages under `/compare/[user1]/[user2]`
     - onboarding/connect flows
     - a docs page at `/api`
   - Most of the visible UI is server-rendered, with a few client components for interactive pieces like search, leaderboard browsing, and time-based views.

3. **Authentication boundary**
   - GitHub OAuth is handled by dedicated routes:
     - `/api/oauth/login`
     - `/api/oauth/callback`
     - `/api/oauth/logout`
   - The app uses a session layer in `src/lib/session.ts` and encrypts stored GitHub tokens via `src/lib/crypto.ts`.
   - The OAuth scope includes `read:user` and `read:org`, which matters because organization access affects commit counting.

4. **Commit ingestion and refresh pipeline**
   - The core job of the system is to fetch commit contribution data from the **GitHub GraphQL API** in `src/lib/github.ts`.
   - Initial onboarding likely performs a full historical backfill; later refreshes are incremental.
   - Refresh logic is centralized in `src/lib/refresh-service.ts` and exposed through:
     - `/api/onboarding/refresh`
     - `/api/jobs/refresh`
     - scripts like `scripts/refresh-user.ts`
   - This is the main external-data pipeline: GitHub → refresh service → database.

5. **Scheduled and manual background work**
   - The repo includes `worker.ts` and a `/api/jobs/refresh` route, indicating scheduled Cloudflare Worker/Cron-style execution.
   - The README says scores are refreshed every 3 days, so there is a background maintenance path separate from user-triggered requests.
   - `scripts/debug-contributions.ts` and `scripts/refresh-user.ts` are operational tools for inspecting or forcing refreshes.

6. **Persistence model**
   - The database schema is managed via SQL migrations in `db/migrations/`.
   - The first migration initializes the main data model; the second adds `score_history`, which supports historical/time-based views and user history.
   - `src/lib/db.ts` is the data access boundary for all reads/writes, so the rest of the app does not talk to Postgres directly.

7. **Leaderboard and ranking APIs**
   - Public read APIs are under `/api/leaderboard`, `/api/rank/[n]`, `/api/user/[login]`, and `/api/stats`.
   - These endpoints are the main read path for the site and for external consumers.
   - Pagination is cursor-based, so the leaderboard is designed for ordered rank traversal rather than offset paging.
   - The API is rate-limited via `src/lib/rate-limit.ts`, which is important because these routes are public and can be hit directly.

8. **Historical and specialized data views**
   - `/api/leaderboard/time-based` and `/api/user/[login]/history` indicate there is a second dimension beyond the current all-time leaderboard: score history over time.
   - The compare pages and profile pages consume the same underlying user/rank data but present it differently.
   - `/api/badge/[login]` generates a rank badge, which is a lightweight public SVG endpoint backed by leaderboard data.

9. **Frontend component boundaries**
   - Reusable UI pieces in `src/components/` are mostly presentation wrappers around the API and page-level data:
     - leaderboard tables
     - time-based leaderboard
     - search panel
     - badge section
     - join/banner and provider setup
   - These components are where the site transitions from server data into interactive browsing.

10. **Runtime and deployment**
   - `open-next.config.ts`, `wrangler.jsonc`, and `worker.ts` show that the app is adapted for Cloudflare’s runtime rather than a standard Node server.
   - `src/lib/runtime-env.ts` suggests the code is aware of environment differences between local dev, Workers, and deployment.
   - Database connectivity is designed around Cloudflare Hyperdrive, with a local Postgres fallback for development.

11. **Operational concerns**
   - The app includes rate limiting, encrypted token storage, and a separate session layer, which are the primary trust/security boundaries.
   - `scripts/migrate.mjs` is the schema bootstrap path, so migrations are part of the deployment story, not just development tooling.
   - The public API, badge endpoint, and refresh jobs are the most important “external surfaces” to capture in an architecture diagram.

Main entry points: [`src/app/api/leaderboard/route.ts`](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/leaderboard/route.ts) (Public API), [`src/lib/refresh-service.ts`](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/refresh-service.ts) (Refresh service), [`src/app/api/oauth/login/route.ts`](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/oauth/login/route.ts) (OAuth routes), [`src/lib/db.ts`](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/db.ts) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["UI"]
  node_node_home["Leaderboard home<br/>page<br/>[page.tsx]"]
  node_node_profile["User profile<br/>page<br/>[page.tsx]"]
  node_node_compare["Compare view<br/>page<br/>[page.tsx]"]
  node_node_onboarding["Onboarding<br/>page<br/>[page.tsx]"]
  node_node_search["Browsing UI<br/>client"]
  node_node_api_doc["API docs<br/>page<br/>[page.tsx]"]
end

subgraph group_group_api["API"]
  node_node_oauth["OAuth routes<br/>[route.ts]"]
  node_node_public_api["Public API<br/>read api<br/>[route.ts]"]
  node_node_badge["Badge API<br/>svg endpoint<br/>[route.ts]"]
  node_node_jobs["Refresh jobs<br/>job routes<br/>[route.ts]"]
end

subgraph group_group_lib["Server logic"]
  node_node_session["Session store<br/>[session.ts]"]
  node_node_crypto["Token crypto<br/>[crypto.ts]"]
  node_node_github["GitHub fetch<br/>graphql client<br/>[github.ts]"]
  node_node_refresh["Refresh service<br/>domain service<br/>[refresh-service.ts]"]
  node_node_db[("Database access<br/>persistence<br/>[db.ts]")]
  node_node_rate["Rate limit<br/>guard<br/>[rate-limit.ts]"]
  node_node_cursor["Cursor paging<br/>[cursor.ts]"]
  node_node_types["Shared types<br/>contracts<br/>[types.ts]"]
end

subgraph group_group_data["Data"]
  node_node_migrations["Migrations<br/>sql schema<br/>[0001_init.sql]"]
end

subgraph group_group_ops["Ops"]
  node_node_worker{{"Worker runtime<br/>cloudflare worker<br/>[worker.ts]"}}
  node_node_opennext["OpenNext config<br/>deployment config"]
  node_node_scripts["Ops scripts<br/>maintenance<br/>[refresh-user.ts]"]
end

node_node_home -->|"loads data from"| node_node_public_api
node_node_home -->|"uses"| node_node_search
node_node_profile -->|"reads"| node_node_public_api
node_node_compare -->|"reads"| node_node_public_api
node_node_onboarding -->|"starts auth"| node_node_oauth
node_node_onboarding -->|"triggers refresh"| node_node_jobs
node_node_oauth -->|"creates session"| node_node_session
node_node_oauth -->|"stores tokens"| node_node_crypto
node_node_oauth -->|"authorizes access"| node_node_github
node_node_public_api -->|"throttled by"| node_node_rate
node_node_public_api -->|"queries"| node_node_db
node_node_public_api -->|"paginates with"| node_node_cursor
node_node_badge -->|"reads"| node_node_db
node_node_jobs -->|"invokes"| node_node_refresh
node_node_refresh -->|"fetches commits"| node_node_github
node_node_refresh -->|"writes scores"| node_node_db
node_node_refresh -->|"decrypts tokens"| node_node_crypto
node_node_refresh -->|"resolves user"| node_node_session
node_node_db -->|"schema from"| node_node_migrations
node_node_worker -->|"schedules"| node_node_jobs
node_node_worker -->|"deploys with"| node_node_opennext
node_node_scripts -->|"applies"| node_node_migrations
node_node_scripts -->|"forces"| node_node_refresh
node_node_scripts -->|"inspects"| node_node_github
node_node_api_doc -->|"documents"| node_node_public_api

click node_node_home "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/page.tsx"
click node_node_profile "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/u/[login]/page.tsx"
click node_node_compare "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/compare/[user1]/[user2]/page.tsx"
click node_node_onboarding "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/onboarding/page.tsx"
click node_node_search "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/components/leaderboard-client.tsx"
click node_node_api_doc "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/page.tsx"
click node_node_oauth "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/oauth/login/route.ts"
click node_node_public_api "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/leaderboard/route.ts"
click node_node_badge "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/badge/[login]/route.ts"
click node_node_jobs "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/jobs/refresh/route.ts"
click node_node_session "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/session.ts"
click node_node_crypto "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/crypto.ts"
click node_node_github "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/github.ts"
click node_node_refresh "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/refresh-service.ts"
click node_node_db "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/db.ts"
click node_node_rate "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/rate-limit.ts"
click node_node_cursor "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/cursor.ts"
click node_node_types "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/types.ts"
click node_node_migrations "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/db/migrations/0001_init.sql"
click node_node_worker "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/worker.ts"
click node_node_opennext "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/open-next.config.ts"
click node_node_scripts "https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/scripts/refresh-user.ts"

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_node_home,node_node_profile,node_node_compare,node_node_onboarding,node_node_search,node_node_api_doc toneBlue
class node_node_oauth,node_node_public_api,node_node_badge,node_node_jobs toneAmber
class node_node_session,node_node_crypto,node_node_github,node_node_refresh,node_node_db,node_node_rate,node_node_cursor,node_node_types toneMint
class node_node_migrations toneRose
class node_node_worker,node_node_opennext,node_node_scripts toneIndigo
```

## Components

### UI

App Router pages and client components for the public site

- [Leaderboard home](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/page.tsx): page · Public landing page and primary leaderboard view · `src/app/page.tsx`
- [User profile](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/u/[login]/page.tsx): page · Profile pages and profile content for /u/[login] · `src/app/u/[login]/page.tsx`
- [Compare view](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/compare/[user1]/[user2]/page.tsx): page · Side-by-side user comparison pages · `src/app/compare/[user1]/[user2]/page.tsx`
- [Onboarding](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/onboarding/page.tsx): page · Connect and onboarding flows for new users · `src/app/onboarding/page.tsx`
- [Browsing UI](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/components/leaderboard-client.tsx): client · Interactive leaderboard, search, and time-based browsing components · `src/components/leaderboard-client.tsx`
- [API docs](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/page.tsx): page · Documentation page for public API usage · `src/app/api/page.tsx`

### API

HTTP routes for auth, reads, badges, and jobs

- [OAuth routes](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/oauth/login/route.ts): auth routes · GitHub login, callback, and logout handlers · `src/app/api/oauth/login/route.ts`
- [Public API](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/leaderboard/route.ts): read api · Leaderboard, rank, user, stats, and history endpoints · `src/app/api/leaderboard/route.ts`
- [Badge API](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/badge/[login]/route.ts): svg endpoint · Public rank badge generation for a user · `src/app/api/badge/[login]/route.ts`
- [Refresh jobs](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/app/api/jobs/refresh/route.ts): job routes · Onboarding and scheduled refresh entrypoints · `src/app/api/jobs/refresh/route.ts`

### Server logic

Shared domain, persistence, auth, and GitHub integration

- [Session store](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/session.ts): session · Session management and authentication state · `src/lib/session.ts`
- [Token crypto](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/crypto.ts): crypto · Encryption for stored GitHub tokens · `src/lib/crypto.ts`
- [GitHub fetch](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/github.ts): graphql client · GitHub GraphQL API access and contribution fetching · `src/lib/github.ts`
- [Refresh service](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/refresh-service.ts): domain service · Core ingestion and score refresh orchestration · `src/lib/refresh-service.ts`
- [Database access](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/db.ts): persistence · Shared Postgres access boundary for reads and writes · `src/lib/db.ts`
- [Rate limit](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/rate-limit.ts): guard · Public API throttling and abuse protection · `src/lib/rate-limit.ts`
- [Cursor paging](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/cursor.ts): paging · Cursor-based traversal for ordered leaderboard reads · `src/lib/cursor.ts`
- [Shared types](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/src/lib/types.ts): contracts · Common domain types shared across app and server code · `src/lib/types.ts`

### Data

Database schema and migrations

- [Migrations](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/db/migrations/0001_init.sql): sql schema · Database schema and score history migrations · `db/migrations/0001_init.sql`

### Ops

Worker runtime and maintenance scripts

- [Worker runtime](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/worker.ts): cloudflare worker · Cloudflare deployment entrypoint and scheduled execution · `worker.ts`
- [OpenNext config](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/open-next.config.ts): deployment config · Next.js adaptation for Cloudflare Workers · `open-next.config.ts`
- [Ops scripts](https://github.com/bennettschwartz/githubcommitsleaderboard/blob/main/scripts/refresh-user.ts): maintenance · Migration, refresh, and debugging scripts · `scripts/refresh-user.ts`

## Connections

- Leaderboard home → Public API: loads data from · Homepage renders leaderboard data through read APIs
- Leaderboard home → Browsing UI: uses · Leaderboard browsing is driven by client-side interaction
- User profile → Public API: reads · Profile pages consume user and history endpoints
- Compare view → Public API: reads · Comparison pages use the same user and rank data
- Onboarding → OAuth routes: starts auth · Onboarding leads users into GitHub OAuth
- Onboarding → Refresh jobs: triggers refresh · Onboarding can kick off a backfill or refresh flow
- OAuth routes → Session store: creates session · OAuth handlers establish application sessions
- OAuth routes → Token crypto: stores tokens · GitHub tokens are encrypted before persistence
- OAuth routes → GitHub fetch: authorizes access · GitHub scopes and identity are verified through GitHub APIs
- Public API → Rate limit: throttled by · Public endpoints are rate limited
- Public API → Database access: queries · Read endpoints fetch leaderboard and user data from Postgres
- Public API → Cursor paging: paginates with · Leaderboard traversal uses cursor-based paging
- Badge API → Database access: reads · Badge generation uses leaderboard data
- Refresh jobs → Refresh service: invokes · Job routes dispatch the refresh workflow
- Refresh service → GitHub fetch: fetches commits · Refresh service pulls contribution data from GitHub
- Refresh service → Database access: writes scores · Refreshes persist current and historical ranking data
- Refresh service → Token crypto: decrypts tokens · Stored tokens are used during GitHub refreshes
- Refresh service → Session store: resolves user · Refreshes are tied back to the authenticated user
- Database access → Migrations: schema from · Database shape is defined by SQL migrations
- Worker runtime → Refresh jobs: schedules · Worker runtime hosts scheduled or manual maintenance execution
- Worker runtime → OpenNext config: deploys with · Cloudflare deployment is configured through OpenNext
- Ops scripts → Migrations: applies · Scripts bootstrap or run schema migrations
- Ops scripts → Refresh service: forces · Operational scripts can trigger refreshes directly
- Ops scripts → GitHub fetch: inspects · Debug scripts inspect contribution data from GitHub
- API docs → Public API: documents · Docs page explains the public API surface
