How bennettschwartz/githubcommitsleaderboard works
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: leaderboard/route.ts Public API · refresh-service.ts Refresh service · login/route.ts OAuth routes · db.ts Database access
Components 22
UI
App Router pages and client components for the public site
- Leaderboard home · Public landing page and primary leaderboard view
src/app/page.tsx - User profile · Profile pages and profile content for /u/[login]
src/app/u/[login]/page.tsx - Compare view · Side-by-side user comparison pages
src/app/compare/[user1]/[user2]/page.tsx - Onboarding · Connect and onboarding flows for new users
src/app/onboarding/page.tsx - Browsing UI · Interactive leaderboard, search, and time-based browsing components
src/components/leaderboard-client.tsx - API docs · Documentation page for public API usage
src/app/api/page.tsx
API
HTTP routes for auth, reads, badges, and jobs
- OAuth routes · GitHub login, callback, and logout handlers
src/app/api/oauth/login/route.ts - Public API · Leaderboard, rank, user, stats, and history endpoints
src/app/api/leaderboard/route.ts - Badge API · Public rank badge generation for a user
src/app/api/badge/[login]/route.ts - Refresh jobs · Onboarding and scheduled refresh entrypoints
src/app/api/jobs/refresh/route.ts
Server logic
Shared domain, persistence, auth, and GitHub integration
- Session store · Session management and authentication state
src/lib/session.ts - Token crypto · Encryption for stored GitHub tokens
src/lib/crypto.ts - GitHub fetch · GitHub GraphQL API access and contribution fetching
src/lib/github.ts - Refresh service · Core ingestion and score refresh orchestration
src/lib/refresh-service.ts - Database access · Shared Postgres access boundary for reads and writes
src/lib/db.ts - Rate limit · Public API throttling and abuse protection
src/lib/rate-limit.ts - Cursor paging · Cursor-based traversal for ordered leaderboard reads
src/lib/cursor.ts - Shared types · Common domain types shared across app and server code
src/lib/types.ts
Data
Database schema and migrations
- Migrations · Database schema and score history migrations
db/migrations/0001_init.sql
Ops
Worker runtime and maintenance scripts
- Worker runtime · Cloudflare deployment entrypoint and scheduled execution
worker.ts - OpenNext config · Next.js adaptation for Cloudflare Workers
open-next.config.ts - Ops scripts · Migration, refresh, and debugging scripts
scripts/refresh-user.ts
Connections 25
- 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