DevTrack

Your developer productivity command center.

Pull your GitHub activity, commit streaks, PR analytics, and coding goals into one clean, self-hostable dashboard — no enterprise plan, no vendor lock-in.

What you get:

• A real-time dashboard for your GitHub stats (streaks, PR analytics, activity)
• Weekly goals with progress tracking
• A shareable public profile (/u/[username])

Live Demo · Dev Guide · Report Bug · Request Feature · Community Discussions · Sponsor

Quick Links

• Demo
• Features
• Getting Started
• Roadmap
• Contributing

---

Demo

Dashboard: streaks, PR analytics, activity heatmap, and goals

Interactive widgets: real-time GitHub data in action

---

Table of Contents

• Why DevTrack?
• Demo
• Features
• Tech Stack
• Project Structure
• Getting Started
• Docker Development Setup
• Roadmap
• Contributing
• Community
• Sponsors
• License
• Contributors

---

Why DevTrack?

Most developers track their work across multiple disconnected tools — GitHub for commits, Jira for tasks, Notion for goals, Slack for standups. None of them give you the full picture.

DevTrack solves this by:

• Consolidating GitHub contributions, PR metrics, and streak data in one view
• Helping you set and visualize personal coding goals with progress tracking
• Keeping your data yours — fully self-hostable with zero vendor lock-in
• Deploying in minutes on the free tier of Next.js + Supabase + Vercel

---

Features

Feature	Description
GitHub OAuth	Sign in with GitHub — no separate account needed
Commit Activity Chart	Visualize daily commit activity with 7d / 14d / 30d / 90d range selector
Commit Streak Tracker	Current streak, longest streak, and active days
PR Analytics	Average review time, merge rate, open/closed PR counts
Top Repositories	Ranked list of most active repos over any time range
Goal Tracker	Set and track personal coding goals with progress bars
Public Profile	Shareable public profile page at /u/[username] with stats and badges
Repository Spotlight	Pin up to 3 repositories to showcase on your public profile
GitHub Achievements	Automatically synced GitHub achievement badges on your public profile
Leaderboard	Opt-in public leaderboard ranked by streak, commits, and PRs
Discord Integration	Streak reminders and milestone alerts via Discord webhooks
Wakatime Integration	Accurate coding time and language usage from Wakatime
Multi-Account Support	Link and switch between multiple GitHub accounts
Weekly Email Digest	Optional Monday morning summary of your coding habits
Data Export	Download all your data in JSON format
AI Weekly Insights	Groq-powered natural language summary of your weekly activity
Heatmap Themes	Default and colour-blind-friendly heatmap colour schemes

---

Tech Stack

Layer	Technology
Frontend	Next.js 14 (App Router), TypeScript, Tailwind CSS
Auth	GitHub OAuth via NextAuth.js v4
Database	Supabase (PostgreSQL) with Row Level Security
API	Next.js Route Handlers (/app/api/)
Charts	Recharts
AI	Groq API
Deployment	Vercel (free tier, auto-deploys from GitHub)

---

Project Structure

devtrack/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── auth/          # GitHub OAuth (NextAuth)
│   │   │   ├── metrics/       # Contributions, streak, PRs, repos
│   │   │   ├── goals/         # Goal CRUD
│   │   │   ├── leaderboard/   # Public leaderboard
│   │   │   ├── public/        # Public profile JSON API
│   │   │   └── user/          # Settings, data export, linked accounts
│   │   ├── dashboard/         # Authenticated dashboard
│   │   ├── u/[username]/      # Public profile pages
│   │   └── page.tsx           # Landing page
│   ├── components/            # Reusable UI components
│   └── lib/
│       ├── auth.ts            # NextAuth config
│       ├── supabase.ts        # Supabase admin client (server-side only)
│       ├── public-profile-data.ts  # GitHub API helpers for public profiles
│       └── github-achievements.ts  # Achievement sync logic
├── supabase/
│   └── migrations/            # Versioned schema migrations
├── e2e/                       # Playwright end-to-end tests
├── test/                      # Unit tests
└── .github/
    ├── workflows/ci.yml       # Type-check + lint on every PR
    └── ISSUE_TEMPLATE/        # Bug, feature, good-first-issue templates

---

API Documentation

DevTrack includes a documented REST API.

Documentation resources:

• docs/api.md — API usage guide
• public/openapi.yaml — OpenAPI 3.1 specification
• /api-docs — Interactive Swagger UI

After starting the development server, open:

http://localhost:3000/api-docs

---

Getting Started

For local development and contributing, see DEVELOPMENT.md. To deploy your own instance, see the Self-Hosting Guide.

Quick Start

1. Clone and install

git clone https://github.com/Priyanshu-byte-coder/devtrack.git
cd devtrack
npm install

2. Set up Supabase

1. Create a free project at supabase.com
2. Run all migrations from supabase/migrations/ in the SQL editor (in order)
3. Copy your Project URL, anon key, and service_role key from Project Settings → API

3. Create a GitHub OAuth App

1. Go to GitHub → Settings → Developer Settings → OAuth Apps
2. Set the callback URL to http://localhost:3000/api/auth/callback/github
3. Copy your Client ID and Client Secret

4. Configure environment

cp .env.example .env.local

Environment Variables

Warning

Never commit .env or .env.local to Git. These files are pre-configured in .gitignore.

Variable	Required	Description
NEXT_PUBLIC_SUPABASE_URL	Yes	Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	Yes	Supabase public anon key
SUPABASE_SERVICE_ROLE_KEY	Yes	Supabase service role key (server-side only)
NEXTAUTH_URL	Yes	Base URL of the app (http://localhost:3000 locally)
NEXTAUTH_SECRET	Yes	Session encryption key — openssl rand -base64 32
GITHUB_ID	Yes	GitHub OAuth App Client ID
GITHUB_SECRET	Yes	GitHub OAuth App Client Secret
ENCRYPTION_KEY	Yes	32-byte hex key — openssl rand -hex 32
GITHUB_TOKEN	No	Personal Access Token to raise GitHub API rate limits
GITHUB_WEBHOOK_SECRET	No	Webhook signature validation key
UPSTASH_REDIS_REST_URL	No	Upstash Redis endpoint for rate limiting
UPSTASH_REDIS_REST_TOKEN	No	Upstash Redis access token
GROQ_API_KEY	No	Groq API key for AI weekly insights
NEXT_PUBLIC_APP_URL	No	Public URL override for generating share links

5. Run locally

npm run dev

Open http://localhost:3000 and sign in with GitHub.

6. Run tests

# Unit tests
npm test

# End-to-end tests (requires Chromium)
npx playwright install --with-deps chromium
npm run test:e2e

### E2E Test Suite (Playwright)

DevTrack ships a Playwright-based end-to-end suite that covers the full user journey — from OAuth sign-in through to dashboard rendering and API route correctness. **No real GitHub or Supabase credentials are needed**; all external calls are mocked inside the specs via `page.route()`.

#### Spec files

| File | What it covers |
|------|----------------|
| `e2e/auth.spec.ts` | Landing page loads, "Sign in with GitHub" button visible, OAuth redirect fires, unauthenticated dashboard redirects |
| `e2e/dashboard.spec.ts` | Dashboard renders all 6 widgets after mock login, no uncaught console errors |
| `e2e/goals.spec.ts` | Create goal → POST fires with correct payload → goal appears in list; delete goal → removed from list |
| `e2e/streak.spec.ts` | Streak widget shows numeric current/longest values, freeze button visible and triggers API call |
| `e2e/api.spec.ts` | `/api/metrics/contributions` returns 200 with valid session, 401 without; `/api/goals` POST returns 401 without session |

The existing smoke specs (`e2e/landing.spec.js`, `e2e/auth-bypass.spec.js`, etc.) remain untouched.

#### Running locally

```bash
# 1. Install Playwright browsers (one-time)
npx playwright install --with-deps chromium

# 2. Run the full suite (dev server auto-starts on port 3002)
npm run test:e2e

# 3. Run a single spec file
npx playwright test e2e/goals.spec.ts

# 4. Open the interactive UI runner
npx playwright test --ui

# 5. View the HTML report after a run
npx playwright show-report
\```

The test server is configured in `playwright.config.mjs`. It auto-starts `next dev` on `http://127.0.0.1:3002` with placeholder credentials so no `.env.local` is required for E2E runs.

#### CI

E2E tests run automatically on every pull request targeting `main` via `.github/workflows/e2e.yml`. The job builds the Next.js app in standalone mode, installs Chromium, runs the suite, and uploads the Playwright HTML report as an artifact retained for 7 days.

4. Everything else in the README stays exactly as it is. The rest of the file — Docker setup, Roadmap, Contributing, Sponsors, etc. — don't touch.

### Visual regression tests

DevTrack uses Playwright screenshot assertions for visual regression coverage of the landing page, sign-in page, dashboard header, public profile, and 404 page.

Run visual regression tests locally:

```bash
npx playwright test -c playwright.visual.config.mjs

Update visual baselines:

npx playwright test -c playwright.visual.config.mjs --update-snapshots

Baselines are stored in tests/snapshots/. Generate and update baselines in the same Linux/Chromium environment used by CI to avoid OS-specific rendering differences. The visual suite uses a fixed 1280x720 viewport and fails when screenshot differences exceed 0.1%.

---

Docker Development Setup

DevTrack includes Docker support for local development, allowing contributors to get started quickly without manually installing dependencies or configuring environments.

Prerequisites

• Docker Desktop (Windows/macOS) or Docker Engine (Linux)
• Docker Compose v2+

Verify installation:

docker --version
docker compose version

Configure Environment Variables

Copy the example environment file:

cp .env.example .env.local

Fill in the required values as described in the Environment Variables section above.

Start the Application

Build and start the development container:

docker compose up --build

The application will be available at:

http://localhost:3000

Stop the Application

docker compose down

Hot Reload Support

The project source code is mounted into the container using Docker volumes.

Any changes made to files on your host machine are automatically reflected inside the container, enabling Next.js hot reload during development without rebuilding the image.

Rebuild After Dependency Changes

If you modify package.json or install new dependencies:

docker compose down
docker compose up --build

Troubleshooting

Remove containers and rebuild from scratch:

docker compose down -v
docker compose up --build

View container logs:

docker compose logs -f

---

Roadmap

Shipped

These features are live in the current version.

Feature	Notes
GitHub OAuth sign-in
Commit activity chart	7d / 14d / 30d / 90d range selector
Commit streak tracker	Current, longest, active days
PR analytics widget	Review time, merge rate, open/closed counts
Top repositories widget
Weekly goal tracker
Dark mode + heatmap themes	Default and colour-blind-friendly
Responsive mobile layout
Public profile (/u/[username])	Shareable stats page
Repository Spotlight	Pin up to 3 repos on public profile
GitHub Achievements sync	Scraped and cached from GitHub profile
Public leaderboard	Opt-in, ranked by streak / commits / PRs
Discord webhook integration	Streak reminders and milestone alerts
Wakatime integration	Coding time and language breakdown
Multi-account GitHub linking	Switch accounts on the dashboard
Weekly email digest	Opt-in Monday morning summary
Data export	Full JSON dump of user data
AI weekly insights	Groq-powered natural language summary
Streak freeze	Protect streak during planned breaks
RSS feed	Atom feed at /u/[username]/feed.xml

In Progress / Planned

Want to contribute? Pick an item below and open an issue or start a PR.

Feature	Difficulty	Issue
Contribution heatmap calendar	Intermediate	#18
Chart type toggle (bar / line)	Intermediate	#17
Language breakdown widget	Intermediate	#32
Activity feed	Intermediate	#33
Auto-progress goals from commits	Advanced	#34
GitLab integration	Advanced	#6
Jira integration	Advanced	—
Team dashboards	Advanced	—
Embeddable stats widgets	Intermediate	—
Mobile app (React Native)	Advanced	—

---

📦 GSSoC Caching Guidelines Reference Manual

Efficient caching improves performance, reduces server load, and enhances user experience in modern web applications.

---

API Response Caching

Use caching for GET requests where data does not change frequently.

Example: Cache-Control: public, max-age=300, stale-while-revalidate=600

---

Frontend Caching

Use tools like React Query or SWR to cache API responses and reduce unnecessary network requests.

---

Server-Side Caching

Use Redis or in-memory caching for:

• expensive computations
• repeated database queries
• frequently accessed data

---

Static Asset Caching

Enable long-term caching for static assets: Cache-Control: public, max-age=31536000, immutable

---

Cache Invalidation Strategy

Always invalidate cache when underlying data changes using:

• versioning
• timestamps
• manual invalidation

---

Best Practices

• Do not cache sensitive data
• Always define TTL (Time To Live)
• Monitor cache hit/miss ratio for performance optimization

Contributing

DevTrack actively welcomes contributors of all skill levels, including GSSoC 2026 participants.

Setup takes under 10 minutes — see DEVELOPMENT.md for the full walkthrough.

How to contribute

1. Browse open issues — start with good first issue
2. Comment on the issue to get assigned before starting work
3. Fork → branch (feat/issue-42-description) → PR against main
4. Ensure CI passes: npm run lint && npm run type-check

See CONTRIBUTING.md for commit style, branch naming, and the review process.

Questions? Open a Discussion.

---

Sponsors

DevTrack is free and open source. Sponsoring helps cover infrastructure costs and accelerates new features.

Tier	Amount	Perks
Coffee	$5 / mo	Your name in this README
Backer	$15 / mo	Name + priority response on issues
Champion	$50 / mo	Name + logo in README + feature request priority
One-time	$10+	One-time thanks, no recurring commitment

Sponsor DevTrack on GitHub

---

Community

Have questions, ideas, or want to connect with other contributors?

• GitHub Discussions — ask questions, share ideas, show what you've built
• Open an Issue — bug reports, feature requests, and good-first-issues
• Email the maintainer — for anything else

All contributors are expected to follow the Code of Conduct.

---

License

MIT — see LICENSE for details.

---

Contributors

Thanks to everyone who has helped build DevTrack. Want to join the list? See CONTRIBUTING.md and pick a good first issue.

---

Built by the DevTrack community · devtrack-delta.vercel.app

Star this repo if DevTrack is useful to you.