Data Flow
Three major data flows cover most of the system’s work: OAuth sign-in, leaderboard ingest, and webhook-driven installation management.
Sign-in flow
Key points:
- The raw GitHub token never touches the database unencrypted.
- The session cookie is httpOnly and Secure — JavaScript on the page cannot read it.
- The
stateparameter is verified to prevent CSRF.
Leaderboard ingest flow
Leaderboard data is computed in three phases: ingest (fetch from GitHub), score (apply weights), serve (read from cache/DB).
The ETag step (Layer 6) means GitHub API calls skip the response body if the underlying data hasn’t changed, using If-None-Match headers against stored ETags in repository_sync_state.
Webhook flow
GitHub sends webhook events when the app is installed or repositories change. These arrive at /api/install/webhook.
If GITHUB_WEBHOOK_SECRET is not set, signature verification is skipped and any HTTP client can send fake events. Always set it in production.
GraphQL proxy flow
The GraphQL proxy at /api/github/graphql forwards authenticated queries to GitHub’s GraphQL API, with caching.
The allowlist prevents the proxy from being used as a general-purpose GitHub API relay.