GitHub Banners

---

A high-performance backend service that generates dynamic banners displaying GitHub user statistics. Perfect for enhancing your GitHub profile README with real-time stats.

github-banners-preview.1.mp4

Overview

GitHub Banners fetches user data from the GitHub API, calculates aggregated statistics (repositories, stars, forks, languages), and renders beautiful SVG banners that automatically update.

Key Features

Feature	Description
Statistics Aggregation	Fetches and calculates total repositories, stars, forks, and language breakdowns
Dynamic SVG Banners	Renders customizable banners with real-time user statistics
Multi-Token Support	Supports multiple GitHub tokens for higher rate limits with automatic rotation
Smart Caching	Multi-layer caching (in-memory + PostgreSQL) with soft/hard TTL strategy
Background Refresh	Automatically refreshes statistics for tracked users
Event-Driven	Kafka-based communication between microservices
Secure Communication	HMAC-based request signing for inter-service authentication

---

Tech Stack

Component	Technology
Language	Go 1.25.5
HTTP Router	chi/v5
Database	PostgreSQL 15
Message Queue	Apache Kafka ( Kraft manager )
GitHub API	go-github/v81
Migrations	goose/v3
Caching	go-cache
Containerization	Docker / Docker Compose

---

Architecture

Github Stats Caching Strategy

Layer	TTL	Behavior
Soft TTL	10 minutes	Serves cached data
Hard TTL	24 hours	Maximum cache lifetime , triggers background refresh
In-Memory	Configurable	Fast access via go-cache
PostgreSQL	Persistent	Durable storage for cached data

Database Schema

Table	Description
banners	Banner configurations and storage paths
github_data.users	GitHub user profile data
github_data.repositories	Repository data linked to users

---

Quick Start

Requirements

• Go 1.25+
• Docker & Docker Compose
• GitHub Personal Access Token(s)

Installation

1. Clone the repository

git clone https://github.com/hurtki/github-banners.git
cd github-banners

2. Configure environment variables

Use .env.example that lay in every folder

Oneliner ( some changes, like api tokens may be required )

cp .env.example .env ; cp ./api/.env.example ./api/.env ; cp ./renderer/.env.example ./renderer/.env ; cp ./storage/.env.example ./storage/.env

• Root .env
• api/.env
• renderer/.env
• storage/.env

3. Start services

Dev mode, 80 port without https

docker compose up --build
# OR Detached mode ( only build logs )
docker compose up --build -d

Production mode, 443 port ( for cloudflare only )

Cloudflare configuration:

Where to get cert and key:

Put certificate cert.pem and private key key.pem to /etc/nginx/ssl/

Docker compose

# production docker compose uses already built images from dockerhub# VER should be in "x.x.x" format# check images: https://hub.docker.com/repository/docker/hurtki/github-banners-api/tagsexport VER=$(git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//')
docker compose -f docker-compose.prod.yaml up -d

Development

For testing consider using "dev" version of docker compose

# Run tests
./run_tests.sh
# CI static check:# fix formatting
gofmt -s -w .# tests check
./run_tests.sh
# spelling ( go install github.com/client9/misspell/cmd/misspell@latest )# it will automatically fix all issues
misspell -source=auto -w .# global api bundle ( only if you touched api.yaml files )# It will combine description of global api in `/docs/api.yaml`# into `bundled.yaml`# for install https://redocly.com/docs/cli/installation
redocly bundle docs/api.yaml -o docs/bundled.yaml

---

Services

Service	Port	Description
nginx	80/443 ( public )	API gateway + static banners
api	80	Main API service
api-psgr	5432	PostgreSQL database
renderer	80	Banner rendering service
storage	80	Banner storage service
kafka	9092	Apache Kafka broker

---

API Endpoints

Method	Endpoint	Description
GET	/banners/preview	Get banner preview for a GitHub user
POST	/banners	Create a new lont-term banner
GET	/{banner-url-path}	Get long term banner ( constantly updating since you created it)

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with Go