[Advanced]: feat(frontend): integrate GitHub Contributors API into Hall of Fame with localStorage caching and rate-limit fallback

[ambicuity]

🧠 Advanced Contributors

This issue requires deep familiarity with:

• GitHub REST API v3 — /repos/{owner}/{repo}/contributors endpoint + Link header pagination
• Browser fetch with error handling and HTTP 403 (rate-limit) detection
• localStorage for client-side response caching with TTL
• Graceful degradation to static JSON fallback
• The Hall of Fame static page (prerequisite: INT-03 must be merged first)

Important

Prerequisites: The Hall of Fame static page (INT-03) must be merged to main before starting.

You must be assigned before starting — comment /assign to claim this issue.

Warning

GitHub unauthenticated API has a 60 requests/hour limit per IP. A naive fetch on every page load will exhaust this for multiple simultaneous users. The localStorage caching strategy is a hard requirement — not optional.

---

🐞 Problem Description

After INT-03 is merged, the Hall of Fame shows hardcoded placeholder cards. Manually maintaining this list defeats the purpose of an automated platform. The integration risk: without caching, the API rate limit breaks the page for anyone who visited in the last hour.

---

💡 Proposed / Expected Solution

Create docs/hall-of-fame.js (new file, loaded only by hall-of-fame.html — NOT bundled into app.js).

1. Fetch with localStorage caching (mandatory):

const CACHE_KEY = 'hof_contributors';
const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour

async function fetchContributors() {
  const cached = JSON.parse(localStorage.getItem(CACHE_KEY) || 'null');
  if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
    return cached.data;
  }
  const res = await fetch(
    'https://api.github.com/repos/ambicuity/New-Grad-Jobs/contributors?per_page=100',
    { headers: { Accept: 'application/vnd.github+json' } }
  );
  if (res.status === 403) { /* rate limited — fall back to contributors-fallback.json */ }
  if (!res.ok) throw new Error(`GitHub API ${res.status}`);
  const data = await res.json();
  localStorage.setItem(CACHE_KEY, JSON.stringify({ timestamp: Date.now(), data }));
  return data;
}

2. Pagination: Loop ?page=N until empty response — handles >100 contributors.

3. Card rendering: Replace placeholder cards with dynamically generated .hof-card elements (exact HTML from INT-03). Map: login → username link, avatar_url → <img>, contributions → count badge.

4. Sorting + rank badges: Sort by contributions descending. Top 3: 🥇 Top Contributor, 🥈 2nd, 🥉 3rd.

5. Graceful degradation:

• HTTP 403: fall back to docs/contributors-fallback.json (a committed JSON snapshot — you must create this)
• Other error: "Data temporarily unavailable — check back soon", retain localStorage data
• Loading: show .skeleton-card CSS while fetch is in flight

---

✅ Acceptance Criteria

• docs/hall-of-fame.js created — loaded only by hall-of-fame.html
• fetchContributors() uses localStorage caching with 1-hour TTL
• HTTP 403 handled gracefully → falls back to docs/contributors-fallback.json
• All pages fetched if contributor count > 100
• Top-3 rank badges rendered (🥇 🥈 🥉)
• Skeleton loading state shown during fetch
• Network error state shown if all fallbacks fail
• docs/contributors-fallback.json committed with current real contributor list
• jobs.json schema unchanged
• No new external JS libraries
• Edge cases: 0 contributors, API timeout, malformed JSON, rate limit on second visit
• pre-commit run --all-files passes
• Existing tests pass (make test)
• PR linked with Fixes #<number>
• PR title: feat(frontend): integrate GitHub API into Hall of Fame with localStorage caching and rate-limit fallback

Area: 🌐 Frontend / website (docs/)

🔗 Additional Context

• GitHub Contributors API
• Link header pagination
• Prerequisite: INT-03 (Hall of Fame static UI) must be merged first

[coderabbitai]

Coding Plan

Summary

• Create a static contributors-fallback.json matching GitHub API schema to serve as rate-limit fallback
• Build hall-of-fame.js following established codebase patterns: element caching, async init, template-literal rendering, and localStorage persistence
• Implement a tiered data strategy: cache → live API with pagination → fallback JSON → stale cache, ensuring graceful degradation at each failure point
• Render sorted contributor cards with rank badges for top 3, using existing .hof-card and .skeleton-card CSS classes from INT-03

Design Choices

Design Choice 1: Fallback JSON schema choice

Options Considered:

1. Use .all-contributorsrc schema (contributions as array of strings like ["code", "doc"])
2. Use GitHub API schema (contributions as integer commit count, html_url for profile)

Chosen Option: 2

Rationale: The rendering code must handle both live API data and fallback data identically, so the fallback should match the GitHub API response structure to avoid conditional mapping logic.

Design Choice 2: DOM container element ID

Options Considered:

1. Assume id="hof-container" matching the page naming convention
2. Assume id="contributors-container" for semantic clarity

Chosen Option: 1

Rationale: Use hof-container to match the hall-of-fame page naming convention and parallel the jobs-container pattern from index.html.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Create Static Fallback Data

Establish the committed JSON snapshot that serves as the rate-limit fallback, ensuring the page remains functional when GitHub API returns HTTP 403.

Create contributors-fallback.json

Create docs/contributors-fallback.json as a static snapshot of contributor data matching the GitHub API response schema.

• Create new file in docs/ directory named contributors-fallback.json
• Structure as an array of contributor objects with fields: login, avatar_url, html_url, contributions (integer)
• Populate with current contributors from .all-contributorsrc, converting contribution types to a reasonable commit count estimate (e.g., count of contribution types × 10, or fetch actual counts once and commit the snapshot)
• Ensure the schema exactly matches what the GitHub API returns so rendering code needs no conditional logic

🤖 Prompt for AI agents

Create a new static JSON file at `docs/contributors-fallback.json` that acts as
a rate-limit fallback for the Hall of Fame page.

- Structure the file as a JSON array of contributor objects
- Each object must include the following fields matching the GitHub API response
schema exactly:
  - `login` (string): GitHub username
  - `avatar_url` (string): URL to the contributor's GitHub avatar
  - `html_url` (string): URL to the contributor's GitHub profile
  - `contributions` (integer): commit count
- Populate using contributors found in `.all-contributorsrc`, converting their
contribution type arrays to an integer commit count estimate (e.g., number of
contribution types × 10)
- The schema must match the GitHub API response exactly so no conditional
mapping logic is needed in the rendering code

Phase 2: Implement Hall of Fame JavaScript

Create the complete docs/hall-of-fame.js file implementing localStorage caching, GitHub API integration with pagination, graceful degradation, and dynamic card rendering.

Task 1: Set up module structure and element caching

Establish the file structure following existing stats.js patterns with constants, element caching, and init wiring.

• Create docs/hall-of-fame.js as a new file
• Define constants at module top: CACHE_KEY = 'hof_contributors', CACHE_TTL_MS = 60 * 60 * 1000, API_BASE = 'https://api.github.com/repos/ambicuity/New-Grad-Jobs/contributors'
• Create elements object caching DOM refs: hofContainer, loading, errorState, themeToggle, backToTop
• Wire init() to DOMContentLoaded at file bottom

Task 2: Implement localStorage caching layer

Build the cache read/write utilities with TTL validation following the localStorage patterns from app.js.

• Create getCachedContributors() function that reads from localStorage, parses JSON, and validates timestamp against TTL
• Return cached data array if valid, null if expired or missing
• Create setCachedContributors(data) function that stores object with timestamp and data fields
• Wrap localStorage writes in try/catch to handle quota errors gracefully

Task 3: Implement GitHub API fetch with pagination

Create the core fetch function handling pagination via Link header and rate-limit detection.

• Create async function fetchFromGitHub() that fetches contributors with ?per_page=100 parameter
• Set Accept: application/vnd.github+json header per API best practices
• Implement pagination loop: continue fetching ?page=N until response array is empty or Link header has no rel="next"
• Accumulate all pages into single array before returning
• Return null and set a flag/marker if HTTP 403 is received (rate limited)
• Throw on other non-OK responses for error handling upstream

Task 4: Implement fallback data fetching

Create the fallback fetch function using the multi-path pattern from existing codebase.

• Create async function fetchFallbackContributors() using the multi-path fallback loop pattern from app.js
• Try paths: ./contributors-fallback.json, ../contributors-fallback.json, /New-Grad-Jobs/docs/contributors-fallback.json
• Return parsed array on success, null if all paths fail

Task 5: Implement main data orchestration function

Create the primary fetchContributors() that orchestrates cache, API, and fallback with proper priority.

• Create async function fetchContributors() as the main entry point
• Check cache first via getCachedContributors() — return immediately if valid
• Attempt fetchFromGitHub() — on success, cache result and return
• On HTTP 403 (rate limit), call fetchFallbackContributors() and return that data (do not cache fallback data)
• On other errors, attempt fallback, then check for stale cache as last resort
• Return null only if all sources fail

Task 6: Implement card rendering with rank badges

Create the template-literal rendering function following the renderJobs() pattern from app.js.

• Create function renderContributors(contributors) accepting sorted array
• Sort contributors by contributions descending before rendering
• Assign rank badges: index 0 gets 🥇 "Top Contributor", index 1 gets 🥈 "2nd", index 2 gets 🥉 "3rd"
• Generate HTML using .map().join('') with staggered --animation-delay CSS variable
• Each card should use .hof-card class (defined by INT-03) and include: avatar image, username link to html_url, contributions count badge, rank badge for top 3
• Use escapeHtml() utility (or create one following app.js pattern) for any user-provided text
• Inject via elements.hofContainer.innerHTML = html

Task 7: Implement loading and error states

Create state management functions for skeleton loading and error display.

• Create showLoading() that displays the .skeleton-card elements (either show existing HTML or inject skeleton markup)
• Create hideLoading() that hides/removes the loading skeleton
• Create showError(message) that displays a user-friendly error state with message like "Data temporarily unavailable — check back soon"
• Handle edge case of 0 contributors with appropriate empty state message

Task 8: Implement init function and theme support

Create the main initialization function following stats.js patterns.

• Create async function init() that: calls initTheme(), shows loading state, awaits fetchContributors(), renders cards or shows error
• Create initTheme() function reading from localStorage with prefers-color-scheme fallback (mirror stats.js implementation)
• Create toggleTheme() for theme button click handler
• Attach event listeners for theme toggle and back-to-top button after async work completes
• Handle scroll listener with { passive: true } for back-to-top visibility

Task 9: Wire script to hall-of-fame.html

Add the script tag to the HTML page to load the new JavaScript file.

• Add <script src="hall-of-fame.js"></script> before closing </body> tag in docs/hall-of-fame.html
• Ensure the script is NOT added to index.html or stats.html — this file is page-specific
• Verify the HTML has the expected container element (id="hof-container") and loading skeleton markup

🤖 Prompt for AI agents

Create `docs/hall-of-fame.js` following the established patterns of `stats.js`
and `app.js`. This phase covers the full implementation of the Hall of Fame page
logic including caching, API integration, pagination, fallback, rendering, and
theme support.

**Module structure & constants (Task 2.1)**
- Define at the top: `CACHE_KEY = 'hof_contributors'`, `CACHE_TTL_MS = 60 * 60 *
1000`, `API_BASE =
'https://api.github.com/repos/ambicuity/New-Grad-Jobs/contributors'`
- Create an `elements` object caching DOM refs for: `hofContainer`, `loading`,
`errorState`, `themeToggle`, `backToTop`
- Wire `init()` to `DOMContentLoaded` at the bottom of the file

**localStorage caching layer (Task 2.2)**
- `getCachedContributors()`: read from localStorage using `CACHE_KEY`, parse
JSON, validate timestamp against `CACHE_TTL_MS`; return data array if valid,
`null` otherwise
- `setCachedContributors(data)`: store `{ timestamp, data }` object; wrap in
try/catch to handle quota errors

**GitHub API fetch with pagination (Task 2.3)**
- `async function fetchFromGitHub()`: fetch with `?per_page=100` and `Accept:
application/vnd.github+json` header
- Loop through pages: continue fetching `?page=N` until response array is empty
or Link header contains no `rel="next"`
- Accumulate all pages into a single array
- Return `null` (and signal rate-limit) on HTTP 403; throw on other non-OK
responses

**Fallback data fetching (Task 2.4)**
- `async function fetchFallbackContributors()`: try paths in order:
`./contributors-fallback.json`, `../contributors-fallback.json`,
`/New-Grad-Jobs/docs/contributors-fallback.json`
- Return parsed array on first success, `null` if all paths fail

**Data orchestration (Task 2.5)**
- `async function fetchContributors()`: implement tiered priority — cache → live
API → fallback on 403 → fallback on other errors → stale cache → `null`
- Do not cache fallback data

**Card rendering with rank badges (Task 2.6)**
- `function renderContributors(contributors)`: sort by `contributions`
descending
- Map index 0 → 🥇 "Top Contributor", index 1 → 🥈 "2nd", index 2 → 🥉 "3rd"
- Build HTML using `.map().join('')` with staggered `--animation-delay` CSS
variable per card
- Each card uses `.hof-card` class and includes: avatar image, username link
(`html_url`), contributions count badge, rank badge for top 3
- Use `escapeHtml()` for user-provided text; inject via
`elements.hofContainer.innerHTML`

**Loading and error states (Task 2.7)**
- `showLoading()`: display `.skeleton-card` elements
- `hideLoading()`: hide/remove skeleton
- `showError(message)`: display user-friendly error (e.g., "Data temporarily
unavailable — check back soon")
- Handle 0 contributors with an empty state message

**Init function and theme support (Task 2.8)**
- `async function init()`: call `initTheme()`, show loading, await
`fetchContributors()`, then render or show error
- `initTheme()`: read from localStorage with `prefers-color-scheme` fallback,
mirroring `stats.js`
- `toggleTheme()`: handle theme button clicks
- Attach event listeners for theme toggle and back-to-top; use `{ passive: true
}` for scroll listener

**Wire to HTML (Task 2.9)**
- Add `<script src="hall-of-fame.js"></script>` before `</body>` in
`docs/hall-of-fame.html` only
- Do not modify `index.html` or `stats.html`
- Confirm `id="hof-container"` container and skeleton markup exist in the HTML

Research

The docs/ directory contains a vanilla JS frontend with app.js (job board) and stats.js (analytics page). Both files use a consistent pattern: async init() wired to DOMContentLoaded, multi-path fetch fallbacks, template-literal card rendering via .map().join('') and innerHTML, and localStorage for persistence (bookmarks, theme, error log). The styles.css already defines .skeleton-card with shimmer animation. The Hall of Fame page (hall-of-fame.html) is assumed to exist from INT-03 with placeholder .hof-card elements and a container for dynamic injection. The .all-contributorsrc file contains 6 contributors but uses a different schema than the GitHub API—the API returns contributions as a number (commits) while the all-contributors format uses an array of type strings.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create a new static JSON file at `docs/contributors-fallback.json` that acts as
a rate-limit fallback for the Hall of Fame page.

- Structure the file as a JSON array of contributor objects
- Each object must include the following fields matching the GitHub API response
schema exactly:
  - `login` (string): GitHub username
  - `avatar_url` (string): URL to the contributor's GitHub avatar
  - `html_url` (string): URL to the contributor's GitHub profile
  - `contributions` (integer): commit count
- Populate using contributors found in `.all-contributorsrc`, converting their
contribution type arrays to an integer commit count estimate (e.g., number of
contribution types × 10)
- The schema must match the GitHub API response exactly so no conditional
mapping logic is needed in the rendering code
===============================================================================

Task: 2

Create `docs/hall-of-fame.js` following the established patterns of `stats.js`
and `app.js`. This phase covers the full implementation of the Hall of Fame page
logic including caching, API integration, pagination, fallback, rendering, and
theme support.

**Module structure & constants (Task 2.1)**
- Define at the top: `CACHE_KEY = 'hof_contributors'`, `CACHE_TTL_MS = 60 * 60 *
1000`, `API_BASE =
'https://api.github.com/repos/ambicuity/New-Grad-Jobs/contributors'`
- Create an `elements` object caching DOM refs for: `hofContainer`, `loading`,
`errorState`, `themeToggle`, `backToTop`
- Wire `init()` to `DOMContentLoaded` at the bottom of the file

**localStorage caching layer (Task 2.2)**
- `getCachedContributors()`: read from localStorage using `CACHE_KEY`, parse
JSON, validate timestamp against `CACHE_TTL_MS`; return data array if valid,
`null` otherwise
- `setCachedContributors(data)`: store `{ timestamp, data }` object; wrap in
try/catch to handle quota errors

**GitHub API fetch with pagination (Task 2.3)**
- `async function fetchFromGitHub()`: fetch with `?per_page=100` and `Accept:
application/vnd.github+json` header
- Loop through pages: continue fetching `?page=N` until response array is empty
or Link header contains no `rel="next"`
- Accumulate all pages into a single array
- Return `null` (and signal rate-limit) on HTTP 403; throw on other non-OK
responses

**Fallback data fetching (Task 2.4)**
- `async function fetchFallbackContributors()`: try paths in order:
`./contributors-fallback.json`, `../contributors-fallback.json`,
`/New-Grad-Jobs/docs/contributors-fallback.json`
- Return parsed array on first success, `null` if all paths fail

**Data orchestration (Task 2.5)**
- `async function fetchContributors()`: implement tiered priority — cache → live
API → fallback on 403 → fallback on other errors → stale cache → `null`
- Do not cache fallback data

**Card rendering with rank badges (Task 2.6)**
- `function renderContributors(contributors)`: sort by `contributions`
descending
- Map index 0 → 🥇 "Top Contributor", index 1 → 🥈 "2nd", index 2 → 🥉 "3rd"
- Build HTML using `.map().join('')` with staggered `--animation-delay` CSS
variable per card
- Each card uses `.hof-card` class and includes: avatar image, username link
(`html_url`), contributions count badge, rank badge for top 3
- Use `escapeHtml()` for user-provided text; inject via
`elements.hofContainer.innerHTML`

**Loading and error states (Task 2.7)**
- `showLoading()`: display `.skeleton-card` elements
- `hideLoading()`: hide/remove skeleton
- `showError(message)`: display user-friendly error (e.g., "Data temporarily
unavailable — check back soon")
- Handle 0 contributors with an empty state message

**Init function and theme support (Task 2.8)**
- `async function init()`: call `initTheme()`, show loading, await
`fetchContributors()`, then render or show error
- `initTheme()`: read from localStorage with `prefers-color-scheme` fallback,
mirroring `stats.js`
- `toggleTheme()`: handle theme button clicks
- Attach event listeners for theme toggle and back-to-top; use `{ passive: true
}` for scroll listener

**Wire to HTML (Task 2.9)**
- Add `<script src="hall-of-fame.js"></script>` before `</body>` in
`docs/hall-of-fame.html` only
- Do not modify `index.html` or `stats.html`
- Confirm `id="hof-container"` container and skeleton markup exist in the HTML

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!