Pulse

Your GitHub profile, decoded. Pulse turns any public GitHub username into a behavioural fingerprint — a clean, black-and-white analytics report that reveals how someone builds, not just what they've shipped.

Type a username, and in seconds Pulse fetches their public activity, measures the signals behind it (when they commit, how they spread across languages, how healthy their repos are), and classifies them into one of five developer archetypes using a machine-learning model trained offline and run at the edge.

---

Highlights

• Instant profile analysis — one username in, a full report out. No login, no OAuth.
• Developer archetypes — a KMeans classifier sorts each profile into one of five behavioural types (e.g. Night Owl, Polyglot, Maintainer).
• Contribution heatmap — a 7×24 grid of commit intensity across the week.
• Language mix — donut breakdown of the languages a developer actually writes.
• Activity trend — weekly commit cadence with a rolling average.
• Repo health scores — stars, forks, recency, README presence and open-issue load rolled into a single 0–100 score per repository.
• Behavioural signals — night-coding %, weekend %, and language breadth.
• Shareable assets — auto-generated badge, social card, and "medal" images served straight from API routes (embed them in a README or share on social).
• All monochrome, all motion — a deliberately restrained black-and-white design system with tasteful animation.

How it works

username ─▶ GitHub REST API ─▶ feature extraction ─▶ ML classifier ─▶ report
             (lib/github.ts)     (lib/analyze.ts)     (lib/classify.ts)

1. Fetch. lib/github.ts is a minimal typed GitHub REST client. It reads public user, repo, language and commit data. A GITHUB_TOKEN (server-side only) raises the rate limit from 60 to 5,000 requests/hour; responses are cached for an hour.
2. Analyze. lib/analyze.ts samples the user's repositories and commits to build a 7-feature behavioural vector, a 7×24 contribution heatmap, a language breakdown, a weekly commit trend, and per-repo health scores.
3. Classify. lib/classify.ts runs nearest-centroid inference in z-scored space against a KMeans model exported to lib/model.json — pure TypeScript, no Python at runtime.
4. Render. The result is a fast server-rendered report at /[username], plus dynamic badge/card/medal images under /api/*.

The ML pipeline

The model lives in ml/ and is trained with scikit-learn:

• Builds a synthetic dataset from five archetype behavioural profiles (300 samples each).
• Fits StandardScaler + KMeans(k=5).
• Maps each learned cluster back to a human-readable archetype via optimal (Hungarian) assignment against the generating labels.
• Exports scaler parameters + cluster centroids to lib/model.json.

Training happens offline; production inference is a few lines of TypeScript. To retrain:

cd ml
pip install -r requirements.txt
python3 train.py   # regenerates ../lib/model.json — commit the result

Feature vector: avgCommitsPerWeek, commitTimeStd, uniqueLanguages, weekendPct, nightPct, readmePct, avgStars

Tech stack

Layer	Choice
Framework	Next.js 16 (App Router, RSC)
Language	TypeScript 5
UI	React 19
Styling	Tailwind CSS v4
Charts	Recharts
Motion	Motion (Framer Motion successor)
Icons	Phosphor Icons, Simple Icons
ML (offline)	Python · scikit-learn
Testing	Playwright

Getting started

# 1. Install dependencies
npm install

# 2. Configure environment (optional but recommended)
cp .env.example .env.local
#   add a GitHub token to raise the API rate limit

# 3. Run the dev server
npm run dev

Open http://localhost:3000 and enter a GitHub username.

Environment variables

Variable	Required	Purpose
GITHUB_TOKEN	No	Raises GitHub API rate limit from 60 → 5,000 req/hr.
SITE_URL	No	Absolute base URL in production, used for social-share images.

.env.local is gitignored and never committed.

Project structure

app/
  page.tsx              Landing page
  [username]/           Server-rendered analysis report
  analyze/              Analyze entry flow
  demo/                 Interactive product demo
  api/
    badge/[username]    Dynamic SVG badge
    card/[username]     Social share card image
    medal/[username]    Archetype "medal" image
lib/
  github.ts             Typed GitHub REST client
  analyze.ts            Feature extraction + report builder
  classify.ts           Nearest-centroid inference
  model.ts / model.json Trained model + loader
  data.ts / colors.ts   Archetype definitions + design tokens
ml/
  train.py              scikit-learn training pipeline
components/             Landing, report, charts, and shared UI

Scripts

npm run dev     # start the dev server
npm run build   # production build
npm run start   # serve the production build
npm run lint    # run ESLint

Deployment

Pulse is a standard Next.js app and deploys anywhere that runs Node — Vercel, or a self-hosted target such as Coolify. Set GITHUB_TOKEN and SITE_URL in the host's environment. No database or external service is required.

Privacy

Pulse only reads public GitHub data and requires no user login. The optional GITHUB_TOKEN is a server-side rate-limit token, never a user credential.

---

Built with Next.js, TypeScript, and a lot of black and white.