🎮 GG Requestz

A modern game discovery and request management platform with IGDB integration, ROMM library support, and powerful search capabilities.

✨ Features

• 🔍 Advanced Search - Search 200,000+ games with filters and real-time results
• 🛡️ Content Filtering - Comprehensive ESRB rating filters, custom content blocks, and global game banning
• 🔒 Global Content Controls - System-wide content filtering that supersedes user preferences for safe environments
• 📚 Game Library Integration - Cross-references requests against your own library. ROMM, Gaseous and Retrom are supported, selected with LIBRARY_KIND
• 🔐 Flexible Authentication - Any standards-compliant OIDC provider (Keycloak, Pocket ID, Authentik, Auth0, Okta, Entra ID) via discovery, plus basic auth with user registration
• 🔑 API Key Management - Generate scoped API keys for programmatic access with Bearer token authentication
• 📚 Interactive API Docs - Complete OpenAPI 3.1 specification with dynamic server URLs at /api/docs
• ⚡ High Performance - Redis caching, hover preloading, and optimized data fetching
• 🎨 Themeable UI - Selectable animated backgrounds and a glass sidebar theme, chosen per user
• 🔔 Outbound Webhooks - Post request events as JSON to any receiver - n8n, a download automation service, a script

📹 Preview

[VIDEO PROMO]

🚀 Quick Start

Get running in 5 minutes with Docker:

# Clone repository
git clone https://github.com/XTREEMMAK/ggrequestz.git
cd ggrequestz

# Configure environment
cp .env.example .env
nano .env  # Add your IGDB credentials and settings

# Start with Docker Compose
docker compose up -d

# Visit http://localhost:3000

📖 Full Quickstart Guide | 🔧 Configuration Options

📖 Documentation

Getting Started

• Quickstart Guide - Docker setup, running from source, environment configuration
• Configuration Guide - every environment variable the code reads
• Architecture Overview - system design and components

Setup

• Database Setup - PostgreSQL settings, migrations, backups
• OIDC / SSO Setup - any OIDC provider, plus roles and admin access
• Production Deployment - reverse proxy, TLS, scaling, upgrades
• Testing - the test layers, and the disposable local stack

Guides

• Integrations - ROMM, Gotify, outbound webhooks
• Custom Navigation - role-based navigation links
• Content Filtering - user and global filtering options
• API Documentation - REST API reference
• Interactive API Docs - OpenAPI specification with live examples
• Release Guide - cutting a release

Development

• Contributing Guide - development guidelines and standards
• Engineering Rules - performance rules, migration constraints, commit discipline
• v1.3 Findings - root causes and open items
• Login Animation Archive - a past investigation
• Changelog - version history

Getting help

1. Setup problems - the guide for that service in docs/setup/
2. An integration isn't working - INTEGRATIONS.md, then the container logs
3. Development questions - CONTRIBUTING.md
4. Bugs and feature requests - open an issue

Maintaining these docs. Documentation must describe shipped behavior. Several guides once documented environment variables that no code read, which produced user-facing bug reports (#4, #7). When you change a documented setting, grep for it in src/ before writing about it, and say so explicitly when a feature is planned rather than implemented.

🔧 Key Features Configuration

Global Content Filtering

Administrators can enforce system-wide content restrictions that supersede individual user preferences:

• Ban Specific Games - Remove specific games by IGDB ID from all search results and listings
• Keyword Blocking - Block games containing specific keywords in their titles
• Genre Filters - Exclude entire genres from appearing in the system
• ESRB Limits - Set maximum ESRB ratings globally
• Mature Content - Hide mature and NSFW content system-wide

Access these controls in Admin Panel → Settings → Content Filtering

Use Case: Perfect for family-friendly environments, educational institutions, or organizations requiring content compliance.

Getting IGDB API Credentials

IGDB (Internet Game Database) provides the game data for G.G. Requestz. To get your API credentials:

1. Create a Twitch Developer Account

   • Visit the Twitch Developer Console
   • Sign in with your Twitch account (or create one if needed)

2. Register Your Application

   • Click "Register Your Application"
   • Fill in the required details:
     • Name: G.G. Requestz (or your preferred name)
     • OAuth Redirect URLs: http://localhost:5174 (for development)
     • Category: Application Integration

3. Get Your Credentials

   • After registration, you'll receive:
     • Client ID → Use as IGDB_CLIENT_ID
     • Client Secret → Use as IGDB_CLIENT_SECRET

4. Detailed Setup Guide

   • For complete setup instructions, visit: https://api-docs.igdb.com/#getting-started
   • The IGDB API uses Twitch's OAuth system for authentication

Note: These credentials are required for the application to fetch game data, search results, and cover images.

🐳 Docker Images

Pre-built Docker images are available:

# Pull latest image
docker pull ghcr.io/xtreemmak/ggrequestz:latest

# Pull specific version
docker pull ghcr.io/xtreemmak/ggrequestz:1.5.0

📋 v1.5.0 Release Notes: The library integration is no longer ROMM-specific: LIBRARY_KIND selects between ROMM, Gaseous and Retrom, and an optional local index answers listing, search and in-library queries from Postgres instead of the backend. Breaking: approval now gates fulfillment, so submitting a request no longer dispatches the outbound webhook. Enable request.auto_approve to keep the old behaviour, or nothing is sent downstream until an administrator approves. See the changelog before upgrading.

🤝 Contributing

See CONTRIBUTING.md for development guidelines.

🙏 Credits

Built and maintained by @XTREEMMAK.

@BlizzHacker contributed the backend-agnostic library layer and all three of its backends (ROMM, Gaseous and Retrom), the local library index that replaced the 2,000-ROM cross-reference window, the request approval workflow and its duplicate guard, the outbound request webhook, and the migration statement-splitter fix, across ten pull requests.

See the contributors graph for everyone who has worked on this.

📝 License

GPLv3 License - see LICENSE file for details.

🔗 Links

• Changelog - Version history and updates
• Issues - Report bugs or request features
• Discussions - Questions and community support