🎬 GitHub Replay

Watch your repository's development history come alive — a cinematic, animated visualization of a day's worth of GitHub activity.

GitHub Replay transforms pull requests, commits, reviews, and issues into a living simulation where contributors are actors moving through a shared workspace, picking up tasks, collaborating, and shipping code.

---

🤖 This entire project was built using Pochi — an AI software engineer. Every component, the GitHub data pipeline, the animation engine, and this README were written by Pochi with zero manual coding.

---

✨ What It Does

Enter any public GitHub repository and a date, and GitHub Replay will:

• Fetch all PRs, commits, reviews, and issues from that day via the GitHub API
• Build a narrative — turning raw events into a sequenced story (who worked on what, when reviews happened, when things merged)
• Animate it on a 2D stage — contributors walk around, pick up tasks, hand them to reviewers, and celebrate merges
• Show a timeline at the top so you can scrub through the day's events

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm (comes with Node)

Install & Run

git clone https://github.com/mufassirkazi/github-visualizer.git
cd github-visualizer
npm install
npm run dev

Open http://localhost:3000 in your browser.

---

🎮 How to Use It

Step 1 — Choose a mode

When you open the app you'll see two options:

Mode	What it does
GitHub Repository	Loads real data from any public GitHub repo
View Demo	Runs a pre-baked scenario — no GitHub account needed

---

Step 2 — Enter a repo and date (GitHub mode)

1. In the Repository URL field, paste either:
   • A full URL: https://github.com/facebook/react
   • Or shorthand: facebook/react
2. Pick a Date — choose a day with a lot of PR activity for the best show. Active open source projects (e.g. vercel/next.js, facebook/react, microsoft/vscode) on any weekday work great.
3. Click Load & Prepare Data

The app will fetch PRs, commits, reviews, and issues for that day, then show you a summary (number of contributors, PRs, commits, reviews).

4. Click Start Visualization — sit back and watch

---

Step 3 — Add a GitHub Token (recommended)

GitHub's API allows only 60 requests/hour without authentication. Any active repo will hit this quickly.

How to create a Personal Access Token (PAT):

1. Go to github.com/settings/tokens
2. Click Generate new token → Generate new token (classic)
3. Give it a name like github-replay
4. Select NO scopes — you only need public data, zero permissions required
5. Click Generate token and copy it (it starts with ghp_)

How to add it in the app:

• Click "Have a GitHub Token?" link at the bottom of the form, OR
• If you hit a rate limit error, a prompt will appear automatically
• Paste your token in the GitHub Token field
• ✅ It's stored only in your browser's localStorage — it's never sent anywhere except directly to api.github.com

Security note: Your token is stored client-side in localStorage under the key gh_token. It is passed directly to the GitHub API from your browser. It is never sent to any backend server — this app has no backend.

---

Controls during playback

Control	What it does
Timeline bar (top)	Click anywhere to jump to that moment in the day
Click an actor	Opens the Inspector panel with details
Click an item (PR card)	Shows PR details
Debug overlay (top-left)	Shows the current event name and index

---

🔐 Security Architecture

This app is entirely client-side — there is no backend, no server, no database. Here's how your token stays safe:

Your Browser
    │
    ├─ localStorage('gh_token')   ← token stored here, never leaves your machine
    │
    └─ fetch('https://api.github.com/...')
           Authorization: token ghp_xxx   ← sent directly to GitHub, not via any proxy

What this means:

• ✅ No server ever sees your token
• ✅ The source code is fully auditable (you're reading it)
• ✅ No .env files, no backend secrets, nothing hidden
• ✅ Token is optional — only needed to raise rate limits from 60 to 5,000 req/hour
• ⚠️ Use a token with no scopes for maximum safety (read-only public data)

---

🏗️ Tech Stack

Layer	Tech
Framework	Next.js 16 (App Router)
UI	React 19 + Tailwind CSS v4
Animation	Framer Motion
3D (future)	React Three Fiber + Three.js
Data	GitHub REST API (no backend — runs entirely in the browser)
Language	TypeScript

---

🗂️ Project Structure

repo-replay/
├── app/
│   ├── page.tsx          # Main UI: controls, loading, replay orchestration
│   ├── layout.tsx        # Root layout
│   └── globals.css       # Global styles & Tailwind config
├── components/
│   ├── Stage.tsx         # The animated 2D workspace
│   ├── Actor.tsx         # Individual contributor character
│   ├── Item.tsx          # PR / Issue card on the board
│   ├── Person.tsx        # Avatar rendering
│   ├── Timeline.tsx      # Scrubber bar at the top
│   ├── Inspector.tsx     # Click an actor/item to see details
│   ├── WorldMap.tsx      # Overview minimap
│   └── lib/
│       ├── engine.ts           # Pure state machine: processEvent(state, event) → state
│       ├── types.ts            # All shared TypeScript types
│       ├── events.ts           # Event definitions
│       ├── githubFetcher.ts    # GitHub API calls + 1hr localStorage cache
│       ├── githubNormalizer.ts # Raw API response → internal ReplayEvent format
│       ├── githubIdentity.ts   # Resolve avatar URLs for contributors
│       ├── prNarrativeBuilder.ts # Sequences events into coherent per-PR stories
│       ├── runner.ts / runner-multi.ts / runner-time.ts  # Playback engines
│       ├── coordinates.ts      # Stage layout constants
│       └── demo-data.ts        # Hardcoded demo scenario
└── public/               # Static assets

---

🧠 How It Works

GitHub REST API
      │
      ▼
githubFetcher.ts        — fetch PRs, commits, reviews, issues for the chosen day
      │
      ▼
githubNormalizer.ts     — normalize raw API objects → ReplayEvent[]
      │
      ▼
prNarrativeBuilder.ts   — group events into per-PR narratives, sequence them in time
      │
      ▼
engine.ts               — pure state machine: processEvent(state, event) → nextState
      │
      ▼
Stage / Actor / Item    — React components render the current EngineState on a timer

The engine is a pure reducer — no side effects, fully testable. The playback loop calls processEvent on a timer and pushes the new state into React.

---

🤝 Contributing

Contributions are very welcome! Some ideas:

• 🎨 Better character sprites / animations
• 📊 Analytics overlay (PR cycle time, review latency)
• 🌐 Support GitLab / Bitbucket APIs
• 📅 Multi-day replay ("replay the whole sprint")
• 🔊 Sound effects
• 📱 Mobile-friendly layout

Submitting a PR

# 1. Fork the repo on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/github-visualizer.git

# 3. Create a feature branch
git checkout -b feat/my-cool-thing

# 4. Make changes, then commit
git add .
git commit -m "feat: describe your change"

# 5. Push and open a PR against main
git push origin feat/my-cool-thing

---

📄 License

MIT — do whatever you want with it. Attribution appreciated but not required.

---

🙏 Acknowledgements

• Pochi — the AI agent that built this entire project
• GitHub REST API for making all this data publicly accessible
• Framer Motion for the buttery animations
• Next.js for the zero-config setup

---

Built with ☕ and a belief that code review should be as fun to watch as a heist movie.