Skip to content

About

Application that analyzes information related to commits, repositories, most-used languages and activity frequency to generate personalized reports and programming habit insights.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

GitHub Wrapped

your annual developer recap, generated from real GitHub activity — Spotify Wrapped for your commit history

Take a look!

GitHub Wrapped analyzes a developer's public GitHub activity — commits, repositories, languages, and working hours — and turns it into a personalized, shareable annual recap, in the style of Spotify Wrapped. The goal isn't just to show numbers: it's to surface behavioral insights that help developers actually understand their habits, backed by an Analytics Engine that computes every statistic before any AI-generated narration touches it.
The platform connects via GitHub OAuth, syncs activity through a background job queue (never inline in an HTTP request), and generates a slide-by-slide Wrapped experience with public, shareable pages and auto-generated Open Graph images.

- Full activity sync via GitHub REST + GraphQL, timezone-aware. - Analytics Engine independent of GitHub, the DB, and the UI.
- AI-narrated insights over pre-computed statistics, never guessed. - Shareable public Wrapped pages with auto-generated OG images.
- Badges, comparisons between users, and year-over-year tracking. - Encrypted tokens, IDOR-safe endpoints, HMAC-verified webhooks.

Objective

The objective of GitHub Wrapped is to transform raw GitHub activity into a visual, entertaining, and genuinely useful year-in-review — one developers actually want to share — while keeping every statistic traceable back to real data instead of an AI's best guess.


Data Collection Module

🔌 GitHub API Client

  • REST client for users, repositories, commits, and languages per repo
  • GraphQL client dedicated to the contribution calendar and combined queries
  • Independent rate-limit handling for REST (5,000 req/hour) and GraphQL (point system)
  • Automatic pagination on every list endpoint

Retry & Resilience

  • Exponential backoff with jitter on 403/429 responses
  • Respects GitHub's retry-after header when present
  • Never retries errors that aren't rate-limit related

Identity Resolution

  • Commit ownership resolved against the authenticated user's login, not just "any linked GitHub account"
  • Fallback to verified account emails for commits GitHub didn't auto-link
  • Covers shared repos, organization repos, and collaborator affiliations correctly

Authentication

OAuth

  • Auth.js with the GitHub provider, database session strategy
  • Minimum scope on first login: read:user user:email public_repo
  • Encrypted access/refresh tokens at rest (AES-256-GCM), never logged, never in plain text

Incremental Authorization

  • Private-repo analysis is opt-in, requested separately from /settings
  • Re-authorization upgrades the scope to repo without a second OAuth App
  • Token persisted on every sign-in, not only on first account link

Job Queue (Inngest)

All heavy processing runs async, outside the lifecycle of an HTTP request — a user with tens of thousands of commits should never be limited by a serverless function timeout.

Sync

  • Initial, incremental, and full sync modes
  • Fan-out across repositories with cursor pagination
  • Progress pollable from the dashboard

Insights

  • Triggered once analytics for a period are ready
  • Feeds only pre-computed metrics into the narration step

Wrapped Generation

  • Generates the full slide deck for a given year
  • Auto-generation cron for closed years, plus on-demand generation

Recurring Jobs

  • Daily reconciliation cron (catches anything webhooks missed)
  • Daily check for auto-generating just-closed years
  • Both are native Inngest crons, not Vercel crons

Analytics Engine

Deliberately decoupled from the GitHub API, the database, and the UI — testable with no network and no live database.

Timezone Normalization

  • Every timestamp converted to the user's local timezone before aggregation, never UTC
  • Most active day/hour, streaks, and activity heatmaps computed on local time
  • Covered by unit tests across multiple timezones

Metrics

  • Favorite language (by bytes, not commit count — a fairer measure)
  • Most active repository, commit streaks, activity by day/hour
  • Language Evolution as a time series, not a single snapshot

Developer Activity Score

  • A composite score — intentionally never called "Productivity Score"
  • More commits doesn't mean more productivity or quality, and the naming says so

Wrapped Experience

Slide Deck

  • Slide-by-slide storytelling, not a static dashboard
  • Covers languages, repos, streaks, activity patterns, and the Activity Score

Sharing

  • Public page per user and year, no authentication required to view
  • Auto-generated Open Graph image per slide for rich link previews
  • One-click share to social platforms, downloadable image, copy link

Insights Engine

  • AI narration strictly over already-computed statistics — never calculates numbers itself
  • Falls back to deterministic templates when no AI key is configured

Comparisons & Gamification

Comparisons

  • Invite another user to compare a period side by side
  • Comparison detail view with per-metric breakdown

Badges

  • Automatic badge awarding based on computed activity
  • Grid view on the dashboard with earned/locked state

Settings

Locale

  • Language preference (English/Spanish), persisted per user
  • Detected automatically on first visit via Accept-Language

Notifications

  • Email preferences via Mailjet
  • Optional — the pipeline works with notifications fully disabled

Private Repos

  • Opt-in toggle, triggers incremental OAuth re-authorization
  • Full purge job available to revoke and delete private-repo data

Account

  • Full data export (JSON), downloadable once ready
  • Account deletion gated by typed username confirmation

Security & Optimization

Prepared for production, not just for a demo.

Security

  • Tokens encrypted at rest, never in logs
  • HMAC-verified GitHub webhooks
  • Ownership checks on every by-ID resource (no IDOR)
  • CSP and standard security headers on all non-API routes

Performance

  • All heavy work offloaded to the job queue
  • Atomic, race-condition-safe rate limiting at the database level
  • Cursor-based pagination for large fan-outs

Testing

  • Unit + integration tests with msw (never against the real GitHub API)
  • E2E coverage with Playwright, including a dedicated security spec
  • CI: typecheck, unit tests, build, and E2E on every push

Tools Used


System Architecture

GitHub (REST + GraphQL) → Data Collector → Job Queue (Inngest) → Database (PostgreSQL) → Analytics Engine → Insights Engine → Dashboard / Wrapped / Sharing

Getting Started

GitHub Wrapped is a hosted web app — there's nothing to install to use it.

  1. Go to the live app (link at the top of this README).
  2. Click "Connect with GitHub" and authorize the OAuth App.
  3. Wait for the first sync to finish (progress is shown on /dashboard).
  4. Open /wrapped to see your recap, or share your public page once it's generated.

Private repositories are never analyzed unless you explicitly opt in from /settings.


Self-Hosting

Running your own instance requires a GitHub OAuth App, a PostgreSQL database, and an Inngest account. Full step-by-step setup (creating each of these, exact env vars, and deploying to Vercel) is in DOCS.

git clone https://github.com/emilymontec/github-wrapped.git; cd github-wrapped
npm install

Environment variables

DATABASE_URL=POSTGRES_POOLED_URL
AUTH_SECRET=AUTH_SECRET
AUTH_URL=http://localhost:3000
GITHUB_CLIENT_ID=GITHUB_OAUTH_CLIENT_ID
GITHUB_CLIENT_SECRET=GITHUB_OAUTH_CLIENT_SECRET
TOKEN_ENCRYPTION_KEY=TOKEN_ENCRYPTION_KEY
INNGEST_EVENT_KEY=INNGEST_EVENT_KEY
INNGEST_SIGNING_KEY=INNGEST_SIGNING_KEY
GITHUB_WEBHOOK_SECRET=GITHUB_WEBHOOK_SECRET
WEBHOOK_BASE_URL=http://localhost:3000
HUGGINGFACE_API_KEY=HUGGINGFACE_API_KEY
HUGGINGFACE_MODEL=HUGGINGFACE_MODEL
MJ_APIKEY_PUBLIC=MJ_APIKEY_PUBLIC
MJ_APIKEY_PRIVATE=MJ_APIKEY_PRIVATE
MAILJET_FROM_EMAIL=MAILJET_FROM_EMAIL

create the .env file and configure the environment variables — see .env.example for details on each one

Database configuration

npx prisma generate
npx prisma migrate dev

Run the application

npm run dev

Application available at: http://localhost:3000


File Structure

github-wrapped/
│
├── app/
│   ├── [username]/wrapped/[year]/
│   ├── account/
│   ├── analytics/
│   ├── api/
│   │   ├── auth/[...nextauth]/
│   │   ├── inngest/
│   │   └── webhooks/github/
│   ├── badges/
│   ├── comparisons/
│   ├── compare/
│   ├── dashboard/
│   ├── insights/
│   ├── score/
│   ├── settings/
│   ├── sync/
│   └── wrapped/
│
├── components/
│   ├── comparisons/
│   ├── dashboard/
│   ├── settings/
│   └── wrapped/
│
├── lib/
│   ├── analytics/
│   ├── auth/
│   ├── gamification/
│   ├── github/
│   ├── insights/
│   ├── jobs/
│   ├── notifications/
│   ├── ratelimit/
│   └── webhooks/
│
├── prisma/
│   ├── schema.prisma
│   └── migrations/
│
├── e2e/
├── public/
├── package.json
├── tsconfig.json
├── next.config.mjs
├── vercel.json
├── .env.example
└── README.md

Contributing

Fork repository

Create branch

git checkout -b feature/my-feature

Commit changes

git commit -m "Add new feature"

Push changes

git push origin feature/my-feature

Open a Pull Request describing the proposed changes.


Author

Emily Monterrosa Castro - Full Stack Developer
GitHub · LinkedIn · Portfolio


License

AGPL-3.0.

See the LICENSE file for additional information.


Appendices

If you want to know more about the system, please check the Documentation.

About

Application that analyzes information related to commits, repositories, most-used languages and activity frequency to generate personalized reports and programming habit insights.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages