GitScope

Your GitHub year in review — like Spotify Wrapped for your code.

Author: Kabir Saamir

---

GitScope is a single-page web app that fetches public GitHub data and presents it as a personalized “year in review”: profile summary, contribution heatmaps (full year, last 90 days, last 30 days), top repositories, language breakdown, and recent activity.

---

Table of contents

• Features
• Tech stack
• Project structure
• Getting started
• Environment variables
• Build & deploy
• API & data sources
• License
• Author

---

Features

• Landing — Enter a GitHub username; optional ⌘K / Ctrl+K shortcut to return to search.
• Loading — 2.5s loading screen while profile, repos, events, and contributions are fetched in parallel.
• Dashboard
  • Profile — Avatar, display name, @username, bio.
  • Stats — Contributions, pull requests, repo count, top language (from aggregated repo languages).
  • Time range — Pills: “This year”, “Last 90 days”, “Last 30 days”; stats and heatmap update per range.
  • Contribution heatmap — GitHub-style grid (Sun–Sat × weeks). Year view: 53 columns + year selector. 90d/30d: variable columns, centered layout; 30d uses larger cells. Hover tooltips show date and contribution level.
  • Achievements — Placeholder achievement cards (early bird, night owl, PR champion, etc.).
  • Activity — Recent events (pushes, PRs, issues, etc.) from the Events API.
  • Top repositories — Table with name, language, stars, last updated (top repos by stars).
  • Languages — Donut chart with hover tooltips; legend shows language and percentage.
  • CTA — Link to GitHub API docs and note about rate limits.

---

Tech stack

Category	Technology
Language	JavaScript (ES modules)
UI	React 18
Build	Vite 6
Styling	CSS (custom properties, no preprocessor)
API	GitHub REST API, GitHub GraphQL API
Fonts	Inter (Google Fonts)

Tags / topics (for GitHub repository topics / submission):

react · vite · javascript · github-api · github-graphql · single-page-application · year-in-review · contribution-graph · github-profile

---

Project structure

GitScope-Main/
├── index.html              # Entry HTML, meta, Inter font
├── package.json             # Scripts, dependencies (React, Vite, @vitejs/plugin-react)
├── vite.config.js           # Vite + React plugin
├── .env.example             # Optional VITE_GITHUB_TOKEN
├── .gitignore
├── README.md                # This file
├── src/
│   ├── main.jsx             # React root, StrictMode
│   ├── index.css            # Global styles, CSS variables (colors, radii, shadows)
│   ├── App.jsx              # View state (form | loading | dashboard), fetch orchestration
│   ├── App.css              # Landing form styles
│   ├── LoadingScreen.jsx     # Loading UI, progress bar
│   ├── LoadingScreen.css
│   ├── Dashboard.jsx        # Dashboard layout, time range, stats, heatmap, tables, charts
│   ├── Dashboard.css
│   ├── ContributionHeatmap.jsx   # Year / 90d / 30d heatmap, month labels, tooltips
│   ├── ContributionHeatmap.css
│   ├── LanguagesChart.jsx    # SVG donut chart, legend, tooltips
│   ├── LanguagesChart.css
│   ├── Achievements.jsx      # Achievement cards (static)
│   ├── Achievements.css
│   └── api/
│       └── github.js        # REST + GraphQL clients, grid builders, aggregateLanguages, formatEvent
├── dist/                    # Production build (generated)
│   ├── index.html
│   ├── favicon.svg
│   └── assets/
└── (optional) .env          # VITE_GITHUB_TOKEN — do not commit

---

Getting started

Requirements: Node.js (v18+ recommended), npm.

# Install dependencies
npm install

# Run development server
npm run dev

Open http://localhost:5173. Enter a GitHub username and click See my wrap. After the loading screen, the dashboard shows that user’s data.

---

Environment variables

Without a token, GitHub allows 60 requests per hour per IP. You may see “Rate limited” after several searches.

Optional: personal access token (5,000 requests/hour)

1. Create a token at GitHub → Settings → Developer settings → Personal access tokens.
   Use “Generate new token (classic)”. No scopes are required for public data.

2. In the project root:

   cp .env.example .env

   Edit .env and set:

   VITE_GITHUB_TOKEN=ghp_yourTokenHere

3. Restart the dev server so Vite picks up the new env.

The .env file is gitignored; do not commit or share your token.

---

Build & deploy

# Production build
npm run build

# Preview production build locally
npm run preview

Output is in dist/. Serve dist with any static host (Vercel, Netlify, GitHub Pages, etc.). No server-side code is required.

---

API & data sources

All data comes from public GitHub APIs.

Data	Source	Endpoint / usage
Profile	REST	GET /users/:username
Repos	REST	GET /users/:username/repos (sort=stars, per_page=10)
Events	REST	GET /users/:username/events (per_page=20)
Contributions (year)	GraphQL	user.contributionsCollection (Jan 1 – Dec 31)
Contributions (90d/30d)	GraphQL	user.contributionsCollection(from, to)

• REST requests use Accept: application/vnd.github.v3+json and User-Agent: GitScope.
• GraphQL requests use the same User-Agent; token is sent as Authorization: Bearer <token> when VITE_GITHUB_TOKEN is set.
• Contribution counts are mapped to heatmap levels 0–4 (GitHub-style buckets).
• Languages are aggregated from each repo’s primary language field; “Top language” and the donut chart use this aggregation.

---

License

This project is provided as-is. Use and modify according to your needs.

---

Author

Kabir Saamir

• GitHub: @kabirsaamir

---

GitScope — built with React, Vite, and the GitHub API.