engineering-overview-pro

---

A free, public SVG card service for GitHub profiles. Embed dynamic stats, language breakdowns, contribution streaks, activity heatmaps, pinned repositories, DevOps signals, and coding activity directly in your README — no sign-up, no install, just a URL.

Built with Node.js, Fastify, and TypeScript. MIT-licensed and ready to self-host.

Maintainer: Enoque Sousa

Quickstart — embed a card in 1 line

Drop this into your README.md, replacing YOUR_LOGIN with your GitHub username:

![](https://your-domain.example/api/stats?username=YOUR_LOGIN)

That's it. The service fetches your public GitHub data and returns an SVG, which any markdown-aware renderer (GitHub, GitLab, dashboards, blog posts) embeds inline.

A profile-ready combo

![Stats](https://your-domain.example/api/stats?username=YOUR_LOGIN)
![Top languages](https://your-domain.example/api/top-langs?username=YOUR_LOGIN&layout=donut)
![Streak](https://your-domain.example/api/streak?username=YOUR_LOGIN)
![Activity](https://your-domain.example/api/activity?username=YOUR_LOGIN)

Available cards

All card endpoints require ?username=<github-login> and return image/svg+xml.

Endpoint	What it shows
/api/stats	Profile statistics — commits, PRs, issues, stars, contributions, rank
/api/top-langs	Most-used languages — layouts: normal, compact, donut, donut-vertical, pie
/api/streak	Contribution streak — mode=daily | weekly
/api/activity	Activity heatmap + radar chart
/api/pin?repo=<name>	Single pinned repository card
/api/pin	Pinned repositories grid
/api/devops	CI/CD, CodeFactor, and security-related signals
/api/coding-stats	Coding activity derived from public GitHub events (no external service)

Utility endpoints

Endpoint	Returns
GET /	Machine-readable JSON catalog of all endpoints with every supported parameter, type, default, and example URL
GET /health	JSON snapshot — uptime, memory, cache size, GitHub rate-limit headroom per token

Customizing

Every card supports the parameters below. Hex colors are passed without the leading #.

Parameter	Type	Default	Notes
theme	dracula-black | pro-dark	dracula-black	Theme id
locale	en | pt-br | es	en	Card copy language
hide_title	bool	false
hide_border	bool	false
custom_title	string ≤100	—	Override default title
border_radius	0–50	12	Card corner radius
bg_color	hex	—	Background
text_color	hex	—	Body text
title_color	hex	—	Title
icon_color	hex	—	Icons
border_color	hex	—	Border
disable_animations	bool	false
cache_seconds	300–86400	14400	CDN/client cache hint (4h default)

/api/stats — extra parameters

Parameter	Type	Default	Notes
include_private	bool	false	Count private contributions (requires expanded PAT scope)
include_archived	bool	true	Include archived repos in star count
include_forks	bool	false	Include forked repos in star count
hide_rank	bool	false	Hide the rank badge
hide	comma list	—	Hide stat rows: stars, commits, prs, issues, contribs
show	comma list	—	Add extra rows: reviews, discussions_started, discussions_answered, prs_merged
line_height	20–40	25	Vertical spacing between rows

/api/top-langs — extra parameters

Parameter	Type	Default	Notes
langs_count	1–100	20	Max languages to display
layout	enum	normal	normal | compact | donut | donut-vertical | pie
hide	comma list	—	Language names to exclude (e.g. HTML,CSS)
exclude_repo	comma list	—	Repositories to exclude from aggregation
include_archived	bool	true	Include archived repos
size_weight	0–1	1	Weight given to byte size
count_weight	0–1	0	Weight given to repo count

/api/streak — extra parameters

Parameter	Type	Default	Notes
mode	daily | weekly	daily	Streak counting granularity
hide_current_streak	bool	false	Hide the current streak section
hide_longest_streak	bool	false	Hide the longest streak section

/api/activity — no extra parameters

Uses only the shared parameters above.

/api/pin — extra parameters

Parameter	Type	Default	Notes
repo	string	—	Repository name (without owner). Omit for the pinned-repos grid; include for a single-repo card.
show_owner	bool	false	Prefix the repo name with owner/
description_lines_count	1–3	1	Lines of description to display

/api/devops — no extra parameters

Uses only the shared parameters above.

/api/coding-stats — extra parameters

Parameter	Type	Default	Notes
langs_count	1–100	5	Number of top languages to display
layout	normal | compact	normal	Card layout style

---

The machine-readable version of this reference (with exact types, ranges, and per-field descriptions) is always available at GET / on any running instance.

Themed examples

<!-- Pro Dark with custom title -->
![](https://your-domain.example/api/stats?username=YOUR_LOGIN&theme=pro-dark&custom_title=My%20GitHub%20Stats)

<!-- Donut top-langs in pt-br -->
![](https://your-domain.example/api/top-langs?username=YOUR_LOGIN&layout=donut&locale=pt-br)

<!-- Single pinned repo -->
![](https://your-domain.example/api/pin?username=YOUR_LOGIN&repo=engineering-overview-pro)

<!-- GitHub-dark color override -->
![](https://your-domain.example/api/stats?username=YOUR_LOGIN&bg_color=0d1117&text_color=c9d1d9&title_color=58a6ff&border_color=30363d)

Rate limits & fair use

• The public instance is rate-limited to 60 requests per minute per client IP.
• Responses use long cache hints (cache_seconds=14400 by default), so README embeds rarely hit the limit.
• The service is best-effort and free. For high-traffic dashboards or guaranteed availability, please self-host (next section).

Self-hosting

The application is a standard Node.js service — no Docker required, though you may containerize it if you prefer.

Requirements

• Node.js 22 or newer
• One GitHub Personal Access Token (PAT) — fine-scoped, public read is enough; private fields require additional scopes

Run locally

git clone https://github.com/enoque-studio/engineering-overview-pro.git
cd engineering-overview-pro
npm install
cp .env.example .env
# Edit .env and set PAT_1
npm run dev

Server listens on http://localhost:3000.

Run in production

npm ci
npm run build
node dist/server.js

Use systemd, pm2, or any process supervisor for restarts and logs. Put a reverse proxy (Nginx, Traefik, Caddy) in front for TLS and set TRUST_PROXY=true so rate limiting sees the real client IP.

Environment variables

Variable	Required	Description
PAT_1	Yes	GitHub PAT. Add PAT_2, PAT_3, … for round-robin rotation — each token shares the 5 000 req/h quota, so more tokens means more headroom.
PORT	No	HTTP port (default 3000)
HOST	No	Bind address (default 0.0.0.0)
LOG_LEVEL	No	Fastify logger level: info, warn, error, debug (default info)
TRUST_PROXY	No	true, false, or comma-separated allow-list. Only enable behind a trusted proxy — otherwise clients can spoof X-Forwarded-For and bypass rate limiting. Default false.
WARM_USERNAMES	No	Comma-separated GitHub usernames to pre-warm in the background. The service silently refreshes their data before the cache expires, eliminating cold-start latency for every card embed.
WARM_INTERVAL_MS	No	How often the background warmer runs in milliseconds. Default 60000 (1 minute). Floor is 30000 (30 s). Warming only fires when the cache has actually expired, so at normal TTLs the warmer makes ≈ 6 GitHub calls per endpoint per day.

There is no default username; every card URL must include ?username=.

Updates

git pull
npm ci
npm run build
# Restart the process

Operational notes

• Keep PATs scoped to the minimum GitHub permissions you need.
• Monitor /health for rate-limit headroom when traffic grows.
• Enable TRUST_PROXY only when a trusted reverse proxy terminates TLS and sets X-Forwarded-For correctly.

Development

Script	Description
npm run dev	Watch-mode dev server (tsx)
npm run build	Compile to dist/
npm start	Run dist/server.js (loads .env when present)
npm test	Unit tests (Vitest, includes GraphQL syntax validation)
npm run test:coverage	Vitest with V8 coverage report
npm run lint	ESLint on src/
npm run typecheck	TypeScript check without emit
npm run format	Prettier write
npm run format:check	Prettier check (CI)
npm run spell	cspell on the full tree
npm run spell:ci	cspell on docs + GraphQL queries (CI subset)
npm run verify	CI parity: format, lint, typecheck, spell, tests, build, npm audit

CI/CD and automation

• CI (.github/workflows/ci.yml) — on every push and PR to main / dev, runs Prettier, ESLint, TypeScript, spell check, Vitest (including GraphQL syntax validation), production build, and npm audit --audit-level=high.
• Dependabot (.github/dependabot.yml) — weekly grouped npm updates (Octokit, Fastify, TypeScript/Vitest clusters) and monthly GitHub Actions updates.
• Releases (.github/workflows/release.yml) — pushing a v* tag (e.g. v1.0.1) creates a GitHub Release with auto-generated notes; npm publish is opt-in via the NPM_PUBLISH repo variable + NPM_TOKEN secret.

Contributing

PRs welcome. See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Security

See SECURITY.md for reporting vulnerabilities. Please do not include real PATs or secrets in issues — use the disclosure channel listed there.

License

MIT — see LICENSE.

Author

Enoque Sousa

⬆ Back to top

Made with ❤️ by Enoque Sousa

Project status: Public service — open for community use