Welcome to GitHub Org Tools — a platform for GitHub organization automation, contributor leaderboards, and analytics.

What this is

If you’ve ever managed a GitHub organization — especially a busy one — you know how hard it is to answer questions like:

• Who’s contributing the most this quarter?
• Which repos are getting the most attention?
• How can I invite 30 new members without doing 30 clicks?

This project exists to answer those questions. It hooks into your org via a GitHub App, pulls data through the GraphQL API, and surfaces it through leaderboards, analytics dashboards, and bulk operations.

How it’s built

┌────────────────────────────────────┐
│         Next.js (App Router)       │
│  ┌────────────┐  ┌──────────────┐  │
│  │  Frontend  │  │  API Routes  │  │
│  │  (React)   │  │  (Backend)   │  │
│  └─────┬──────┘  └──────┬───────┘  │
│        │                │          │
│        └────────┬───────┘          │
│                 │                  │
│         ┌───────┴───────┐         │
│         │  Supabase DB  │         │
│         └───────────────┘         │
└────────────────────────────────────┘
          │                │
          ▼                ▼
    GitHub OAuth      GitHub GraphQL
    + App API         + REST API

The backend lives entirely inside Next.js API routes — no separate server, no microservices. Sessions are stored in Supabase. GitHub API calls go through either the user’s OAuth token or a GitHub App installation token. Everything is designed to be deployable to Vercel as a single unit.

What you can do

Here’s what’s ready today:

• OAuth sign-in with a GitHub App — sessions stored in Supabase
• GitHub App installation flow — grants the app org-level API access
• GraphQL proxy at POST /api/github/graphql — typed, allowlisted, safe
• Organization management — mass invite, team management, role management
• Leaderboards — per-contributor, per-repository, per-team, with configurable scoring rules
• Analytics — dashboards, repository breakdowns, contributor profiles, heatmaps, timelines

The sidebar has the full breakdown. The Core Concepts section is a good place to start for the big picture.

Quick start

The detailed setup guide lives in Local Development, but here’s the gist:

cp example.env .env.local
pnpm install
pnpm dev

You’ll need a GitHub App configured and a Supabase project. Follow the full walkthrough in the setup guide for both.

Product routes

All organization-specific pages live under /[organization]/:

Environment variables

You’ll need these in .env.local:

Required

Strongly recommended

If you skip the security variables, the app falls back to derived values from your GitHub client secret and app ID. Fine for local dev, but don’t do it in production.

Backend structure

Here’s what’s in lib/:

lib/
├── analytics/         # Rollup queries for analytics
├── api/               # Shared API client (axios)
├── auth/              # OAuth, crypto, sessions, installations
├── cache/             # Redis cache helpers
├── constants/         # Time constants, rate limits
├── env/               # Zod-validated env access
├── errors.ts          # Error message mapping
├── github/            # Octokit, GraphQL proxy, data fetching
├── leaderboard/       # Leaderboard pipeline orchestration
├── organization/      # Organization-specific helpers
├── scoring/           # Scoring engine, rules, normalization
├── supabase/          # DB repositories
├── test/              # Test utilities
├── utils.ts           # cn() and friends

Where to go next

• System Architecture — layers, data flow, design decisions
• Authentication — OAuth, sessions, security
• GraphQL API — how to query GitHub data
• Scoring Overview — how leaderboard scoring works
• Deployment — step-by-step local setup