Spike: Leaderboard SVG rendering strategy

[Z-M-Huang]

Context

The leaderboard feature (v0.3.0) stores a registry of users in a public gist and each user's public profile in their own public gist. The CLI cc-proficiency leaderboard command fetches N+1 gists (1 registry + N profiles) and displays a text table.

We want to render a leaderboard SVG that can be embedded in READMEs, hosted in the registry gist alongside cc-proficiency-registry.json.

Open Questions

1. GitHub API Rate Limits

• Unauthenticated: 60 requests/hour
• Authenticated (PAT): 5,000 requests/hour
• With 50 users, each render = 51 API calls
• At 30-min intervals: 102 calls/hour (within PAT limit, but scales poorly)
• At what user count does this break? ~98 users hits the 5k/hour limit at 30-min intervals

2. Rendering Options

Option	How	Pros	Cons
A. N+1 gist reads	Scheduled Action fetches each profile gist, renders SVG	Simple, uses existing infrastructure	O(N) API calls per render, rate limit ceiling
B. Pre-aggregated leaderboard.json	Each user's mergeAndPush also pushes their scores to a central "scores" gist (append-only)	1 API call to read all scores	Requires write access to central gist from every user (not possible without shared token)
C. Webhook on public gist update	GitHub doesn't support gist webhooks	N/A	Not possible
D. Users push scores to registry via Issue	Extend join Issue to include scores, or add periodic "update" Issues	Central aggregation, no N reads	More Issues, more Action runs, complex parsing
E. Static site (GitHub Pages)	Action builds HTML page with embedded data, deploys to Pages	Rich interactivity, no SVG size limits	Needs a separate repo or branch, more infra
F. Single aggregated JSON in registry gist	The registration Action also reads the user's profile and stores scores inline in registry.json	1 API call for leaderboard render (just read registry)	Registration Action becomes heavier, scores stale until next join/leave
G. Scheduled Action aggregates into registry gist	Every 30 min, Action reads N profiles, writes leaderboard.json + SVG to registry gist	Decouples aggregation from rendering	Still O(N) reads, but only in the Action

3. Recommended Investigation

1. Confirm exact GitHub API rate limits for gist reads via PAT on self-hosted runner
2. Prototype Option G (simplest v1) with 5-10 test users
3. Measure actual latency and API call count
4. If rate limits become an issue, migrate to Option F (inline scores in registry.json, updated by the registration Action + a periodic "refresh" Action that reads profiles in batches)

4. SVG Design Questions

• Top 20 users, dark theme matching badge style
• Dimensions: ~600px wide, ~500px tall (20 rows)
• Show: rank, username, average score, 5 domain scores
• Highlight: streaks, achievement counts?
• Update frequency: every 30 minutes (or on registry change + scheduled)

Acceptance Criteria

• Research confirmed: GitHub API rate limits documented for our use case
• Recommended rendering strategy chosen with justification
• Prototype SVG renderer (src/renderer/leaderboard-svg.ts)
• Scheduled workflow (.github/workflows/leaderboard-render.yml)
• Embeddable URL documented

[Z-M-Huang]

Spike Research Findings

Rate Limit Analysis

GitHub API limits: 60/hr unauthenticated, 5,000/hr with PAT.

Each render cycle (Option G): 1 registry read + N profile reads + 1 gist write = N + 2 API calls

Users (N)	Calls/cycle	At 30-min (calls/hr)	At 60-min	Headroom (5k/hr)
10	12	24	12	99.5%
50	52	104	52	97.9%
100	102	204	102	95.9%
500	502	1,004	502	79.9%
1,000	1,002	2,004	1,002	59.9%

Account Safety Concern

Even within rate limits, high-frequency automated gist reads from a single PAT can trigger GitHub's abuse detection. GitHub's docs warn that automated requests should:

• Use conditional requests (If-None-Match / ETags) to avoid counting cached responses
• Add delays between requests (not burst N reads simultaneously)
• Avoid sustained high-frequency patterns that look like scraping

Risk: A scheduled Action reading 50+ gists every 30 minutes from a personal account could get flagged, even if technically within rate limits. This is the biggest concern with Option G at scale.

Mitigation Strategies

1. Use conditional requests (ETags): GitHub API supports If-None-Match headers — cached responses don't count against rate limits. If most profiles haven't changed since last check, most calls return 304 (free).

2. Batch with delays: Add 100ms delay between profile reads to avoid burst patterns.

3. Reduce frequency: Render every 60 min instead of 30 min (halves API usage).

4. Option F migration: At ~50+ users, migrate to inline scores in cc-proficiency-registry.json. The registration Action reads the user's profile once on join, and a periodic refresh Action reads profiles in batches (e.g., 10 profiles per run, cycling through all users over multiple runs). This reduces per-cycle reads from N to ~10.

5. GitHub App instead of PAT: A GitHub App has separate rate limits (5,000/hr per installation) and doesn't risk the personal account. More setup but safer at scale.

Options Comparison

Option	API Cost	Complexity	Account Risk	Scalability
A. N+1 reads per render	O(N)/cycle	Low	Medium-High at scale	~500 users safe
B. Users push to central gist	O(1) read	Medium	None	Unlimited
F. Inline scores in registry	O(1) read + O(N) refresh	Medium	Low (batched)	Unlimited
G. Scheduled Action aggregates	O(N)/cycle	Low	Medium at scale	~500 users

Recommended Strategy

Phase 1 (now, <50 users): Option G with safeguards

• Scheduled Action every 60 min (not 30)
• Add 100ms delays between profile reads
• Use ETags for conditional requests
• Monitor API usage

Phase 2 (50+ users): Migrate to Option F

• Registration Action reads profile and stores scores inline in registry.json
• Periodic refresh Action updates stale scores in batches (10/run)
• Leaderboard SVG rendered from registry.json (0 profile reads)
• CLI also benefits (1 call instead of N+1)

Phase 3 (if needed): GitHub App

• Separate rate limits, no personal account risk
• Only if Phase 2 is insufficient

SVG Design (for implementation)

• Dimensions: 600px wide, 62 + N*24 + 40 tall (max 582px for 20 rows)
• Dark theme: Reuse existing C colors, DOMAIN_COLORS, SANS/MONO fonts from badge renderer
• Layout: Rank | @username | avg score | 5 domain mini-bars with score overlays
• Animated variant: Row fade-in staggered, domain bars width-animate (SMIL)
• Hosted in registry gist alongside cc-proficiency-registry.json

Implementation Files

NEW: src/renderer/leaderboard-svg.ts          — static SVG renderer
NEW: src/renderer/leaderboard-animated-svg.ts — animated variant  
NEW: src/scripts/render-leaderboard.ts        — standalone render script
NEW: .github/workflows/leaderboard-render.yml — scheduled Action
MOD: src/cli/services/leaderboard.ts          — (Phase 2) read from leaderboard.json

Open Questions

1. Should we start with 60-min intervals to be safe, or 30-min?
2. Max rows: top 20 or top 50?
3. Should registration workflow trigger an immediate render?
4. Should we pursue a GitHub App early, or only if PAT-based approach hits issues?