# IGDB Integration

TurboVault integrates with the [Internet Game Database (IGDB)](https://www.igdb.com/) 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`:

```bash
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

```bash
# 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).