turbovault-app/docs/IGDB_INTEGRATION.md

IGDB Integration

TurboVault integrates with the Internet Game Database (IGDB) to automatically enrich your games with metadata, cover art, and genre information.

How It Works

1. Background sync runs every 30 minutes (configurable)
2. Searches IGDB for games without metadata
3. Creates suggestions with confidence scores (0-100%)
4. Users review and approve/reject matches
5. Metadata applied when approved (cover art, genres, release dates)

Setup

Get IGDB Credentials

1. Create account at https://dev.twitch.tv
2. Register an application
3. Copy Client ID and Client Secret

Configure

Add to .env:

IGDB_CLIENT_ID=your_client_id_here
IGDB_CLIENT_SECRET=your_client_secret_here

Enable for Users

New users have IGDB sync enabled by default. Users can opt-out in Settings.

Usage

Review Matches

Visit /igdb_matches to see pending suggestions.

Each suggestion shows:

• Game title
• Cover art
• Platform
• Confidence score
• Genres from IGDB

Actions:

• ✅ Approve - Apply metadata to your game
• ❌ Reject - Dismiss suggestion
• 🔄 Sync Now - Manually trigger sync for your games

Manual Commands

# Trigger sync manually
task igdb:sync

# Check sync status
task igdb:status

# Clear stuck jobs
task igdb:clear

How Matching Works

Confidence scoring:

• Title match: 0-70 points
• Platform match: 0-30 points
• 100% = exact title + platform match

Fallback search:

• First tries with platform filter
• Falls back to no platform if no results

Genre mapping: IGDB genres are automatically mapped to your local genres (e.g., "Role-playing (RPG)" → "RPG").

Platform Support

26 platforms supported including:

• Nintendo (NES, SNES, N64, GameCube, Wii, Switch)
• PlayStation (PS1-PS5, PSP, Vita)
• Xbox (Xbox, 360, One, Series X/S)
• Sega (Genesis, Dreamcast, Saturn)
• PC platforms (Steam, Epic, GOG)

Background Job

Schedule: Every 30 minutes
Configuration: config/queue.yml
Job: IgdbSyncJob

The job:

• Only processes users with igdb_sync_enabled: true
• Skips games with igdb_id already set
• Creates up to 3 match suggestions per game
• Respects rate limits (4 requests/second)

API Rate Limits

• Limit: 4 requests per second
• Handled: Automatic 0.3s delay between requests
• Caching: Games cached in igdb_games table

Disabling IGDB

Users can disable in Settings → "Enable IGDB metadata sync"

Admins can disable globally by removing env vars or stopping the recurring job.

Attribution

IGDB attribution link in footer (required by IGDB terms).