GameVault

A competitive gaming stats API built with Go. Track players, record matches, view leaderboards in real-time, and get AI-powered performance coaching.

Tech Stack

• Go with Chi router
• PostgreSQL — player and match data
• Redis — cache-aside for leaderboard queries
• WebSocket — real-time leaderboard updates
• Gemini API — AI-generated performance advice
• Docker Compose — one-command setup

Architecture

cmd/server/          → Entry point, route registration
internal/
  handler/           → HTTP handlers (auth, player, match, AI, health)
  service/           → Business logic
  repository/        → Database layer with interfaces
  middleware/        → Auth (JWT), CORS, request logging
  cache/             → Redis cache-aside with graceful degradation
  ws/                → WebSocket hub for real-time broadcasts
  ai/                → Gemini API integration
  model/             → Data models
migrations/          → SQL schema

API Endpoints

Method	Route	Auth	Description
POST	/players	Public	Register a new player
POST	/login	Public	Login and receive JWT
GET	/leaderboard	Public	Paginated leaderboard (cached)
GET	/health	Public	Health check
GET	/profile	Required	View player profile
POST	/match	Required	Record a match result
GET	/ai/advice	Required	AI performance coaching
GET	/ws	Public	WebSocket connection

Quick Start

Prerequisites: Docker and Docker Compose

# 1. Clone the repo
git clone https://github.com/yashasvi16/gamevault.git
cd gamevault

# 2. Add your Gemini API key (optional)
echo "GEMINI_API_KEY=your_key_here" > .env

# 3. Start everything
docker-compose up --build

The API will be available at http://localhost:8080.

Running Without Docker

# Start PostgreSQL and Redis manually, then:
export DATABASE_URL="postgres://user:pass@localhost:5432/gamevault?sslmode=disable"
export JWT_SECRET="your-secret-key"
export REDIS_URL="localhost:6379"
export GEMINI_API_KEY="your-key"      # optional

go run ./cmd/server

Running Tests

go test ./... -v

Key Design Decisions

• Interface-based repositories — enables unit testing with mock implementations
• Transactional match recording — match insert + player stats update in a single DB transaction
• Redis graceful degradation — API continues working if Redis is unavailable
• Cache-aside pattern — leaderboard responses cached with 30s TTL
• Structured logging — uses log/slog throughout