GitHub Visualizer turns public GitHub contribution data into a shareable 3D builder profile card. It combines a FastAPI backend, a Vite/React frontend, and a Three.js scene to render a lightweight identity card for developers and open-source maintainers.
The project is designed as an open-source maintainer workflow demo: the backend normalizes contribution signals, the frontend renders a visual card, and the deployment docs keep token-protected GitHub API calls on the server.
web/: Vite, React, Three.js, and React Three Fiber frontend.backend/: FastAPI API service, profile scoring, GitHub GraphQL adapter, and SQLite render leaderboard.docs/: deployment notes, product notes, and asset references..github/: issue templates, pull request template, and CI workflow.
- Input a GitHub username and render a builder profile.
- Generate a score and rank from contribution activity, repositories, stars, followers, and streaks.
- Use deterministic mock data for local demos or GitHub GraphQL data in production.
- Record render events for a lightweight leaderboard.
- Keep
GITHUB_TOKENon the backend only.
Backend:
cd backend
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 127.0.0.1 --port 8890Frontend:
cd web
npm ci
npm run dev -- --host 0.0.0.0 --port 5173Local dev uses Vite's /api proxy by default. Set web/.env.local only when the backend is not reached through the proxy:
VITE_API_BASE=http://127.0.0.1:8890The default backend mode is deterministic mock data:
DATA_SOURCE=mockTo use real GitHub data, create backend/.env from backend/.env.example and set:
DATA_SOURCE=github
GITHUB_TOKEN=<server-side-github-token>The frontend must never receive GITHUB_TOKEN.
Backend:
cd backend
PYTHONPATH=. python3 -m unittest discover -s testsFrontend:
cd web
npm run lint
npm run buildGitHub Actions runs backend tests plus frontend type-check and build on pull requests and pushes to main.
Deploy web/ to Vercel with:
Root Directory: web
Install Command: npm ci
Build Command: npm run build
Output Directory: dist
Run the backend on a private server behind nginx or another reverse proxy. See docs/deployment.md for the systemd and nginx outline.
Contributions are welcome for scoring logic, GitHub data quality, accessibility, visual polish, deployment docs, CI hardening, and tests. Read CONTRIBUTING.md before opening larger changes.
Good first maintenance tasks include:
- Add regression tests for scoring edge cases.
- Improve GitHub GraphQL error handling.
- Add accessible fallbacks for the 3D scene.
- Extend deployment documentation.
- Add screenshots or preview assets to the README.
Report suspected vulnerabilities privately. Do not open public issues for token exposure or backend authorization problems. See SECURITY.md.
MIT