### Run from Source Development

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/QUICKSTART.md

Install dependencies, configure the environment, and start the development server.

```bash
npm install
cp .env.example .env
npm run dev
```

--------------------------------

### Start Database Services for Development

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/QUICKSTART.md

Start the required database services and run migrations when developing from source.

```bash
docker compose up -d postgres redis
npm run db:migrate
```

--------------------------------

### Start development server

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Launch the local development server.

```bash
npm run dev
```

--------------------------------

### Start and Monitor Application

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/QUICKSTART.md

Commands to start the Docker services and monitor their status and logs.

```bash
# Start all services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f ggrequestz
```

--------------------------------

### Start ggrequestz with Docker

Source: https://github.com/xtreemmak/ggrequestz/blob/main/README.md

Commands to clone the repository, prepare the environment file, and start the services using Docker Compose.

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

--------------------------------

### SQL Migration Example

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Example of a migration script for adding a user preferences table, following the project's requirement for descriptive naming and schema management.

```sql
// migrations/007_add_user_preferences.sql
-- Add user preferences table
CREATE TABLE ggr_user_preferences (
  id SERIAL PRIMARY KEY,
  user_id VARCHAR(255) NOT NULL REFERENCES ggr_users(id),
  preference_key VARCHAR(100) NOT NULL,
  preference_value TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(user_id, preference_key)
);

-- Add indexes for performance
CREATE INDEX idx_user_preferences_user_id ON ggr_user_preferences(user_id);
CREATE INDEX idx_user_preferences_key ON ggr_user_preferences(preference_key);
```

--------------------------------

### POST /api/setup/check

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Check service connectivity during setup.

```json
{
  "service": "igdb_api"
}
```

```json
{
  "success": true,
  "service": "igdb_api",
  "status": "connected",
  "details": "IGDB API accessible"
}
```

--------------------------------

### Pull and start pre-built images

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/QUICKSTART.md

Use these commands to pull the pre-built image from the GitHub Container Registry and start the services in detached mode.

```bash
docker compose pull
docker compose up -d
```

--------------------------------

### Install dependencies

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Install required project dependencies using npm.

```bash
npm install
```

--------------------------------

### Configure environment variables

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Create the .env file from the example template.

```bash
cp .env.example .env
# Edit .env with your configuration
```

--------------------------------

### Start Authentik test environment

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/TESTING.md

Command to bring up the Authentik test profile.

```bash
docker compose -f docker-compose.test.yml --profile authentik up -d
```

--------------------------------

### Execute database/setup-postgres.js

Source: https://github.com/xtreemmak/ggrequestz/blob/main/scripts/README.md

Command to run the direct PostgreSQL setup script for environments with direct database access.

```bash
node scripts/database/setup-postgres.js setup
```

--------------------------------

### Conventional Commits format examples

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/dev-notes/ENGINEERING_RULES.md

Examples of commit messages following the Conventional Commits specification.

```text
feat: add OIDC discovery document support
fix: add timeout to ROMM authentication request
docs: rewrite OIDC setup guide for generic providers
refactor: consolidate duplicate ROMM fetch implementations
```

--------------------------------

### Initialize database from source

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/DATABASE_SETUP.md

Start the PostgreSQL service and manually trigger the database migration process when running the application from source.

```bash
docker compose up -d postgres    # or point .env at your own server
npm run db:migrate
```

--------------------------------

### Database Setup and Migration Commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/scripts/README.md

Commands to initialize the database, run pending migrations, check status, and warm up the cache using the db-manager.js script.

```bash
# Initialize database
node scripts/database/db-manager.js init

# Run all pending migrations
node scripts/database/db-manager.js migrate

# Check migration status
node scripts/database/db-manager.js status

# Warm up cache
node scripts/database/db-manager.js warm
```

--------------------------------

### Build images locally

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/QUICKSTART.md

Use these commands to build the images from source locally before starting the services.

```bash
docker compose build
docker compose up -d
```

--------------------------------

### Enable Debug Environment Variables

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/CONFIGURATION.md

Examples of how to run the development server with specific debug flags enabled for troubleshooting.

```bash
# Enable all debug logging
DEBUG_AGE_RATINGS=true DEBUG_IGDB_QUERIES=true DEBUG_USER_AUTH=true VITE_DEBUG_VIEWPORT_CACHING=true npm run dev

# Enable only viewport caching debug (useful for mobile optimization)
VITE_DEBUG_VIEWPORT_CACHING=true npm run dev

# Enable only authentication debug
DEBUG_USER_AUTH=true npm run dev
```

--------------------------------

### Monitor migration logs

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/TESTING.md

Example output from the application logs showing the migration sequence and skipped migrations.

```text
⏭️  Skipping 001_initial_schema.sql (already executed)
⏭️  Skipping 002_complete_schema_updates.sql (already executed)
🔄 Running migration: 008_add_animated_background_preference.sql
```

--------------------------------

### Start stack with external access

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/TESTING.md

Configures the application to accept connections from a different host by setting the bind address and origin host.

```bash
GGR_TEST_HOST=0.0.0.0 GGR_TEST_ORIGIN_HOST=<lan-ip> \
  docker compose -f docker-compose.test.yml up -d app
```

--------------------------------

### cURL API Integration with API Key

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Command line examples for interacting with the API using an Authorization header.

```bash
# Store your API key
export GGR_API_KEY="ggr_your_api_key_here"

# Get game details
curl -H "Authorization: Bearer $GGR_API_KEY" \
     "https://your-domain.com/api/games/72129"

# Search for games
curl -H "Authorization: Bearer $GGR_API_KEY" \
     "https://your-domain.com/api/search?q=zelda"

# Add to watchlist
curl -X POST \
     -H "Authorization: Bearer $GGR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"igdb_id":"72129"}' \
     "https://your-domain.com/api/watchlist/add"

# Get popular games with filtering
curl -H "Authorization: Bearer $GGR_API_KEY" \
     "https://your-domain.com/api/games/popular?page=1&limit=20"
```

--------------------------------

### Define a new migration file

Source: https://github.com/xtreemmak/ggrequestz/blob/main/migrations/README.md

Example of a migration file structure using defensive SQL practices.

```sql
-- Migration: 009_add_widget_preference
-- Description: Per-user widget layout preference

ALTER TABLE ggr_users
  ADD COLUMN IF NOT EXISTS widget_layout JSONB DEFAULT '[]'::jsonb;
```

--------------------------------

### GET /api/version

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Returns application version, environment details, and feature availability.

```APIDOC
## GET /api/version

### Description
Returns application version and feature information.

### Method
GET

### Endpoint
/api/version

### Response
#### Success Response (200)
- **version** (string) - Application version
- **name** (string) - Application name
- **environment** (string) - Deployment environment
- **buildTime** (string) - Build timestamp
- **features** (object) - Enabled features
- **api** (object) - API version and endpoint list
```

--------------------------------

### GET /api/user/preferences - Retrieve user preferences

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Get the user's current content filtering preferences.

```json
{
  "success": true,
  "preferences": {
    "content_filter_level": "mild",
    "hide_mature_content": true,
    "hide_nsfw_content": true,
    "max_esrb_rating": "T",
    "custom_content_blocks": ["violence", "gambling"],
    "preferred_genres": ["Adventure", "RPG"],
    "excluded_genres": ["Horror", "Sports"],
    "apply_to_homepage": true,
    "apply_to_popular": true,
    "apply_to_recent": false,
    "apply_to_search": true
  }
}
```

--------------------------------

### GET /api/version

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Returns the application version, environment details, build time, enabled features, and available API endpoints.

```json
{
  "version": "1.5.0",
  "name": "gg-requestz",
  "environment": "production",
  "buildTime": "2026-07-26T12:00:00Z",
  "features": {
    "oidc": true,
    "basicAuth": true,
    "redis": true,
    "romm": true,
    "typesense": false
  },
  "api": {
    "version": "v1",
    "endpoints": [
      "/api/games",
      "/api/auth",
      "/api/requests",
      "/api/watchlist",
      "/api/admin"
    ]
  }
}
```

--------------------------------

### GET /admin/api/navigation

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieve all navigation items. Requires navigation.manage permission.

```APIDOC
## GET /admin/api/navigation

### Description
Get all navigation items. Requires `navigation.manage` permission.

### Method
GET

### Endpoint
/admin/api/navigation
```

--------------------------------

### Write integration tests with mocked fetch

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Example of an integration test in tests/integration/ that mocks the global fetch function.

```javascript
// tests/integration/romm-token-lifecycle.test.js
global.fetch = vi.fn().mockResolvedValue(response(500));

const { isRommAvailable } = await freshRomm();
await expect(isRommAvailable()).resolves.toBe(false);
```

--------------------------------

### GET /api/romm/recent

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieve recently added ROMs from the ROMM library.

```APIDOC
## GET /api/romm/recent

### Description
Get recently added ROMs from the ROMM library.

### Method
GET

### Endpoint
/api/romm/recent

### Parameters
#### Query Parameters
- **page** (number) - Optional - Page number
- **limit** (number) - Optional - Results per page

### Response
#### Success Response (200)
- **success** (boolean) - Status
- **roms** (array) - List of ROMs
- **hasMore** (boolean) - Pagination indicator
```

--------------------------------

### Write unit tests for pure functions

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Example of a unit test for a utility function located in src/tests/unit/ using Vitest.

```javascript
// src/tests/unit/utils-direct.test.js
import { describe, expect, it } from "vitest";
import { formatDate } from "$lib/utils.js";

describe("formatDate", () => {
  it("formats an ISO date for display", () => {
    expect(formatDate("2023-01-01")).toBe("Jan 1, 2023");
  });
});
```

--------------------------------

### Configure ROMM Server URLs

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/CONFIGURATION.md

Example configuration for environments where the internal service address differs from the public-facing URL.

```env
ROMM_SERVER_URL=http://romm.media.svc:8080
ROMM_SERVER_URL_PUBLIC=https://romm.example.com
```

--------------------------------

### Python API Integration with API Key

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Example using the requests library to manage authentication via a session object.

```python
import requests
import os

# Load API key from environment
API_KEY = os.getenv('GGR_API_KEY')
BASE_URL = 'https://your-domain.com/api'

# Create session with auth header
session = requests.Session()
session.headers.update({
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
})

# Search for games
response = session.get(f'{BASE_URL}/search', params={
    'q': 'zelda',
    'page': 1,
    'per_page': 10
})
games = response.json()

# Add to watchlist
response = session.post(f'{BASE_URL}/watchlist/add',
    json={'igdb_id': '72129'})
result = response.json()

# Get popular games
response = session.get(f'{BASE_URL}/games/popular', params={
    'page': 1,
    'limit': 20
})
popular_games = response.json()

# Get game details
response = session.get(f'{BASE_URL}/games/72129')
game = response.json()
```

--------------------------------

### cURL API Integration with Session Cookie

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Command line examples for interacting with the API using a session cookie header.

```bash
# Get game details
curl "https://your-domain.com/api/games/72129"

# Search with authentication
curl -H "Cookie: session=your-token" \
     "https://your-domain.com/api/search?q=zelda"

# Add to watchlist
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Cookie: session=your-token" \
     -d '{"igdb_id":"72129"}' \
     "https://your-domain.com/api/watchlist/add"
```

--------------------------------

### Commit changes using Conventional Commits

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```bash
git commit -m "feat: add user profile customization"
git commit -m "fix: resolve database connection timeout"
git commit -m "docs: update API documentation"
git commit -m "test: add integration tests for auth"
```

--------------------------------

### Run End-to-end Tests

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/TESTING.md

Commands to install Playwright browsers, seed the test database, and execute the end-to-end test suite.

```bash
npx playwright install     # once; CI does this itself
make test-seeded
npm run test:e2e
```

--------------------------------

### Set up database

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Initialize the database using either Docker or a local PostgreSQL instance.

```bash
# Option 1: Use Docker
docker compose up -d postgres redis
npm run db:migrate

# Option 2: Local PostgreSQL
createdb ggrequestz
npm run db:init
```

--------------------------------

### GET /api/cache/stats

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Get cache statistics.

```APIDOC
## GET /api/cache/stats

### Description
Get cache statistics.

### Method
GET

### Endpoint
/api/cache/stats

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **stats** (object) - Cache statistics for redis and memory

#### Response Example
{
  "success": true,
  "stats": {
    "redis": {
      "connected": true,
      "keyCount": 1250,
      "memoryUsed": "15.2MB"
    },
    "memory": {
      "keyCount": 500,
      "estimatedSize": "5.1MB"
    }
  }
}
```

--------------------------------

### Expected RomM broken state logs

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/TESTING.md

Example of the log output when the RomM broken state is triggered.

```text
🚫 ROMM refused to issue a token: the account lacks the 'roms.read' scope...
⚠️ ROMM availability probe failed (http_403)
```

--------------------------------

### JavaScript API Integration with API Key

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Example of using the Fetch API with an Authorization header containing a Bearer token.

```javascript
const API_KEY = process.env.GGR_API_KEY; // Store securely in environment variables

// Search for games
const response = await fetch(
  "https://your-domain.com/api/search?q=zelda&page=1&per_page=10",
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  },
);
const data = await response.json();

// Add to watchlist
await fetch("https://your-domain.com/api/watchlist/add", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ igdb_id: "72129" }),
});

// Get popular games
const popular = await fetch(
  "https://your-domain.com/api/games/popular?limit=20",
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  },
);
const games = await popular.json();
```

--------------------------------

### Python API Integration with Session Cookie

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Example using the requests library to perform requests with session cookies.

```python
import requests

# Search for games
response = requests.get('https://your-domain.com/api/search', {
    'q': 'zelda',
    'page': 1,
    'per_page': 10
})
games = response.json()

# Add to watchlist with session
session = requests.Session()
session.cookies.set('session', 'your-session-token')
session.post('https://your-domain.com/api/watchlist/add',
             json={'igdb_id': '72129'})
```

--------------------------------

### GET /api/romm/recent - Get recent ROMs

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieve a list of recently added ROMs from the ROMM library.

```json
{
  "success": true,
  "roms": [
    {
      "id": "123",
      "name": "Super Mario Bros.",
      "platform": "NES",
      "added_at": "2025-09-29T12:00:00Z"
    }
  ],
  "hasMore": true
}
```

--------------------------------

### Measure TTFB for cold start regression test

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/TESTING.md

Use this curl command to measure the time to first byte for the /login endpoint to verify the v1.3 cold-start fix.

```bash
curl -w "%{time_starttransfer}\n" -o /dev/null -s http://127.0.0.1:3100/login
```

--------------------------------

### Test ROMM Connection via G.G Requestz API

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/guides/INTEGRATIONS.md

Verify the integration by sending a POST request to the G.G Requestz setup check endpoint.

```bash
curl -X POST http://your-ggrequestz-host/api/setup/check \
  -H "Content-Type: application/json" \
  -d '{"service": "romm_library"}'
```

--------------------------------

### Clone the repository

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Initial steps to download the project source code.

```bash
git clone https://github.com/XTREEMMAK/ggrequestz.git
cd ggrequestz
```

--------------------------------

### Example of anti-pattern commit history

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/dev-notes/ENGINEERING_RULES.md

This shows an example of poor commit history where multiple unrelated changes are bundled into single commits, violating the one logical change per commit rule.

```text
687aef7 Release v1.2.5: Global content filtering and critical bug fixes
bf494c2 Release v1.2.3: Critical security fixes and granular permissions
b6b29a7 Complete UI improvements from previous session
```

--------------------------------

### GET /api/images/proxy

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Proxy and cache external images.

```APIDOC
## GET /api/images/proxy

### Description
Proxy and cache external images.

### Method
GET

### Endpoint
/api/images/proxy

### Parameters
#### Query Parameters
- **url** (string) - Required - Image URL to proxy

### Response
#### Success Response (200)
- **binary** (blob) - Image binary data with appropriate headers.
```

--------------------------------

### JavaScript API Integration with Session Cookies

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Example of using the Fetch API in a browser environment where session cookies are handled automatically.

```javascript
// Search for games
const response = await fetch("/api/search?q=zelda&page=1&per_page=10");
const data = await response.json();

// Add to watchlist
await fetch("/api/watchlist/add", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ igdb_id: "72129" }),
});
```

--------------------------------

### GET /api/games/recent

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieves a list of recently released games.

```APIDOC
## GET /api/games/recent

### Description
Get recently released games.

### Method
GET

### Endpoint
/api/games/recent

### Parameters
#### Query Parameters
- **page** (number) - Optional - Page number (default: 1)
- **limit** (number) - Optional - Results per page (default: 16)
- **user_id** (string) - Optional - User ID for content filtering
```

--------------------------------

### GET /api/search

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Search for games using query parameters.

```APIDOC
## GET /api/search

### Description
Search games with IGDB integration.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query
- **page** (number) - Optional - Page number
- **per_page** (number) - Optional - Results per page
- **autocomplete** (boolean) - Optional - Return autocomplete suggestions

### Response
#### Success Response (200)
- **success** (boolean) - Search status
- **hits** (array) - Search results
- **found** (number) - Total results found
- **page** (number) - Current page
```

--------------------------------

### Clone and Configure Repository

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/QUICKSTART.md

Commands to clone the repository and prepare the environment configuration file.

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

# Copy environment template
cp .env.example .env

# Edit .env with your settings
nano .env
```

--------------------------------

### GET /api/igdb

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Proxy for IGDB API to retrieve game data.

```APIDOC
## GET /api/igdb

### Description
Direct IGDB API proxy for game data retrieval.

### Method
GET

### Endpoint
/api/igdb

### Parameters
#### Query Parameters
- **action** (string) - Required - IGDB action (search, details, etc.)
- **query** (string) - Optional - Search query
- **limit** (number) - Optional - Result limit
```

--------------------------------

### Development Commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/QUICKSTART.md

List of available npm scripts for development, building, testing, and linting.

```bash
npm run dev         # Dev server on :5174
npm run build       # Production build
npm run preview     # Preview the production build
npm run check       # svelte-check
npm run lint        # prettier --check (this is what CI gates on)
npm run format      # prettier --write
npm run test:unit   # vitest
npm run test:e2e    # playwright
```

--------------------------------

### GET /api/user/preferences

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieve the user's content filtering preferences.

```APIDOC
## GET /api/user/preferences

### Description
Get the current user's content filtering preferences.

### Method
GET

### Endpoint
/api/user/preferences

### Response
#### Success Response (200)
- **success** (boolean) - Status of the operation
- **preferences** (object) - User preference settings
```

--------------------------------

### Monitor database initialization and migration logs

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/DATABASE_SETUP.md

Use this command to watch the logs for schema initialization and migration progress during the Docker container startup.

```bash
docker compose logs -f ggrequestz | grep -iE "schema|migration"
```

--------------------------------

### GET /api/games/recent Response

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Returns a list of recently released games.

```json
{
  "success": true,
  "games": [...],
  "hasMore": true,
  "total": 500
}
```

--------------------------------

### GET /api/health

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Health check endpoint for monitoring system status.

```APIDOC
## GET /api/health

### Description
Health check endpoint for monitoring.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **status** (string) - System status
- **timestamp** (string) - Current timestamp
- **uptime** (number) - System uptime in seconds
- **version** (string) - Application version
```

--------------------------------

### Run database/db-manager.js Commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/scripts/README.md

Usage instructions for the unified database manager script, which handles initialization, migrations, and cache operations.

```bash
node scripts/database/db-manager.js <command>

Commands:
  init     - Initialize database with core tables
  migrate  - Run pending database migrations
  status   - Show migration status and pending migrations
  warm     - Warm up the games cache
  stats    - Show cache statistics
  fix      - Fix migration table issues
```

--------------------------------

### GET /api/games/{id}

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieve detailed information for a specific game by its ID.

```APIDOC
## GET /api/games/{id}

### Description
Retrieves detailed information for a specific game.

### Method
GET

### Endpoint
/api/games/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the game
```

--------------------------------

### POST /admin/api/keys/create

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Create a new API key. Requires apikey.create permission.

```APIDOC
## POST /admin/api/keys/create

### Description
Create a new API key. Requires apikey.create permission.

### Method
POST

### Endpoint
/admin/api/keys/create

### Request Body
- **name** (string) - Required - Name for the API key
- **scopes** (array) - Required - List of scopes
- **expires_at** (string) - Optional - Expiration timestamp

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **key** (string) - The generated API key
- **id** (integer) - Key ID
```

--------------------------------

### GET /api/cache/stats

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieves current cache statistics for Redis and memory storage.

```json
{
  "success": true,
  "stats": {
    "redis": {
      "connected": true,
      "keyCount": 1250,
      "memoryUsed": "15.2MB"
    },
    "memory": {
      "keyCount": 500,
      "estimatedSize": "5.1MB"
    }
  }
}
```

--------------------------------

### GET /api/browse/publishers/{slug}

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Browse games filtered by a specific publisher slug.

```APIDOC
## GET /api/browse/publishers/{slug}

### Description
Browse games by publisher.

### Method
GET

### Endpoint
/api/browse/publishers/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The publisher slug
```

--------------------------------

### GET /api/browse/genres/{slug}

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Browse games filtered by a specific genre slug.

```APIDOC
## GET /api/browse/genres/{slug}

### Description
Browse games by genre.

### Method
GET

### Endpoint
/api/browse/genres/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The genre slug

#### Query Parameters
- **page** (number) - Optional - Page number
- **limit** (number) - Optional - Results per page
```

--------------------------------

### Format and check code style

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Use these commands to format your code or verify that it meets the project's formatting standards as enforced by CI.

```bash
# Format code (this is also the "fix" command)
npm run format

# Check formatting, as CI does
npm run lint

# Type-check Svelte components
npm run check
```

--------------------------------

### Configure optional services in .env

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/QUICKSTART.md

Environment variables to enable RomM integration, Gotify notifications, and outbound webhooks.

```bash
# ROMM Integration
ROMM_SERVER_URL=http://your-romm-server
# Recommended for RomM 5.0+: a Client API Token with the "roms.read" scope.
# It does not expire and avoids storing your password.
ROMM_API_TOKEN=your_client_api_token
# Fallback for RomM 4.x:
#ROMM_USERNAME=your_username
#ROMM_PASSWORD=your_password

# Gotify Notifications
GOTIFY_URL=http://your-gotify-server
GOTIFY_TOKEN=your_token

# Outbound request webhook (any JSON receiver)
REQUEST_WEBHOOK_URL=https://your-webhook-endpoint
```

--------------------------------

### Run database migrations

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CHANGELOG.md

Command to execute database migrations manually.

```bash
npm run db:migrate
```

--------------------------------

### Project Directory Layout

Source: https://github.com/xtreemmak/ggrequestz/blob/main/src/tests/README.md

The file structure for the unit and integration testing projects.

```text
src/tests/                          # the "unit" Vitest project (jsdom)
├── README.md
├── setup.js                        # browser API mocks
├── mocks/
│   └── env.js                      # $env/dynamic/private stub
└── unit/
    ├── auth-utils.test.js          # isAuthenticated, display name, initials
    ├── basic-auth-token.test.js    # session token signing
    ├── performance.test.js         # prefetch, metrics, image/bundle helpers
    └── utils-direct.test.js        # truncateText, formatDate, safeAsync, withTimeout

tests/                    # everything outside src/
├── integration/                    # the "integration" Vitest project (node)
│   └── romm-token-lifecycle.test.js
├── e2e/                            # Playwright
│   ├── global-setup.js             # refuses to run without the test stack
│   ├── helpers.js                  # signIn(), seeded credentials
│   ├── auth.spec.js
│   └── homepage.spec.js
└── fixtures/
    └── games.json                  # seed data for the Docker stack
```

--------------------------------

### GET /api/games/popular

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieve a list of popular games with optional pagination and content filtering.

```APIDOC
## GET /api/games/popular

### Description
Fetches a list of popular games. Supports pagination and user-based content filtering.

### Method
GET

### Endpoint
/api/games/popular

### Parameters
#### Query Parameters
- **page** (number) - Optional - Page number
- **limit** (number) - Optional - Items per page
- **user_id** (string) - Optional - User ID for applying content filters
```

--------------------------------

### GET /api/search

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Search for games based on a query string. Supports pagination parameters.

```APIDOC
## GET /api/search

### Description
Search for games using a query string. Supports pagination parameters like page and limit.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query string
- **page** (number) - Optional - Page number (starts at 1)
- **limit** (number) - Optional - Items per page (max: 100)
- **per_page** (number) - Optional - Items per page (max: 100)
```

--------------------------------

### Create manual release tags

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/guides/RELEASE_GUIDE.md

Alternative method to create a release by manually updating the package version and pushing git tags.

```bash
# Update package.json version
npm version 1.0.3

# Create and push the tag
git tag v1.0.3
git push origin main
git push origin v1.0.3
```

--------------------------------

### GET /api/watchlist/status/{id}

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Checks if a specific game is currently in the user's watchlist.

```APIDOC
## GET /api/watchlist/status/{id}

### Description
Check if game is in user's watchlist.

### Method
GET

### Endpoint
/api/watchlist/status/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The IGDB ID of the game
```

--------------------------------

### Run release helper script

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/guides/RELEASE_GUIDE.md

Use the npm script or the shell script directly to automate the release process for a specific version.

```bash
# Create a release for version 1.0.3
npm run release 1.0.3
```

```bash
scripts/create-release.sh 1.0.3
```

--------------------------------

### GET /api/games/popular Response

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Returns a list of popular games from IGDB with pagination support.

```json
{
  "success": true,
  "games": [
    {
      "igdb_id": "72129",
      "title": "The Legend of Zelda: Breath of the Wild",
      "cover_url": "https://images.igdb.com/igdb/image/upload/t_cover_big/co1nqg.jpg",
      "rating": 97.5,
      "popularity_score": 98.2,
      "platforms": ["Nintendo Switch", "Wii U"],
      "genres": ["Adventure", "Role-playing (RPG)"]
    }
  ],
  "hasMore": true,
  "total": 1000
}
```

--------------------------------

### GET /api/health

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Health check endpoint for monitoring system status, uptime, and version.

```json
{
  "status": "ok",
  "timestamp": "2026-07-26T12:00:00Z",
  "uptime": 3600,
  "version": "1.5.0"
}
```

--------------------------------

### Run database migration commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/dev-notes/ENGINEERING_RULES.md

Use these npm scripts to execute migrations or check the current migration status.

```bash
npm run db:migrate
npm run db:status
```

--------------------------------

### Configure Gotify Environment Variables

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/guides/INTEGRATIONS.md

Set the Gotify URL and application token to enable notifications. Both variables are required; notifications will be skipped if either is missing. Ensure the token is generated from a Gotify application, not a client.

```env
GOTIFY_URL=https://gotify.example.com
GOTIFY_TOKEN=<application token>
```

--------------------------------

### GET /api/games/{id}

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieves detailed information for a specific game using its IGDB ID.

```APIDOC
## GET /api/games/{id}

### Description
Get detailed game information by IGDB ID.

### Method
GET

### Endpoint
/api/games/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The IGDB ID of the game
```

--------------------------------

### Reconfigure and restart the application

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/TESTING.md

Export the necessary environment variables and restart the application using the test docker-compose configuration.

```bash
export ROMM_SERVER_URL=http://romm:8080
export ROMM_API_TOKEN=rmm_...
docker compose -f docker-compose.test.yml --profile romm --profile oidc up -d app
```

--------------------------------

### GET /api/games/popular

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieves a list of popular games from IGDB with optional pagination and user filtering.

```APIDOC
## GET /api/games/popular

### Description
Get popular games from IGDB.

### Method
GET

### Endpoint
/api/games/popular

### Parameters
#### Query Parameters
- **page** (number) - Optional - Page number (default: 1)
- **limit** (number) - Optional - Results per page (default: 16)
- **user_id** (string) - Optional - User ID for content filtering

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **games** (array) - List of game objects
- **hasMore** (boolean) - Indicates if more pages are available
- **total** (number) - Total count of games
```

--------------------------------

### GET /api/watchlist/status/{id} Response

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Checks if a specific game is currently in the user's watchlist.

```json
{
  "success": true,
  "inWatchlist": true
}
```

--------------------------------

### Backup and Restore Database with Docker Compose

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/DATABASE_SETUP.md

Use these commands to dump the database to a file and restore it into an empty database. It is recommended to take a dump before every upgrade as there is no automated rollback path.

```bash
# Dump
docker compose exec -T postgres pg_dump -U postgres ggrequestz > backup.sql

# Restore into an empty database
docker compose exec -T postgres psql -U postgres -d ggrequestz < backup.sql
```

--------------------------------

### GET /api/browse/genres/{slug} Response

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Returns a list of games filtered by the specified genre slug.

```json
{
  "success": true,
  "genre": {
    "name": "Role-playing (RPG)",
    "slug": "role-playing-rpg"
  },
  "games": [...],
  "pagination": {
    "page": 1,
    "hasMore": true,
    "total": 2500
  }
}
```

--------------------------------

### Project Directory Structure

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Overview of the project file organization, including routes, library utilities, components, and configuration files.

```text
src/
├── routes/                 # SvelteKit routes
│   ├── +layout.svelte     # Main app layout
│   ├── +page.svelte       # Homepage
│   ├── api/               # API endpoints
│   ├── admin/             # Admin interface
│   ├── auth/              # Authentication
│   └── setup/             # First-run setup
├── lib/                   # Shared utilities
│   ├── auth.js           # Authentication helpers
│   ├── database.js       # Database client
│   ├── cache.js          # Caching utilities
│   └── utils.js          # General utilities
├── components/           # Reusable UI components
├── app.css              # Global styles
└── app.html            # HTML template

scripts/                  # Build and utility scripts
migrations/              # Database migrations
static/                  # Static assets
```

--------------------------------

### GET /api/search Autocomplete and Search

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Retrieves autocomplete suggestions or full search results from IGDB.

```json
{
  "success": true,
  "suggestions": [
    "The Legend of Zelda",
    "Zelda: Breath of the Wild",
    "Zelda: Tears of the Kingdom"
  ]
}
```

```json
{
  "success": true,
  "hits": [
    {
      "document": {
        "id": "72129",
        "name": "The Legend of Zelda: Breath of the Wild",
        "summary": "Game description...",
        "cover": {
          "url": "https://images.igdb.com/igdb/image/upload/t_cover_big/co1nqg.jpg"
        },
        "platforms": [{ "name": "Nintendo Switch" }, { "name": "Wii U" }],
        "genres": [{ "name": "Adventure" }, { "name": "Role-playing (RPG)" }],
        "rating": 97.5,
        "first_release_date": 1488499200
      }
    }
  ],
  "found": 1,
  "page": 1
}
```

--------------------------------

### POST /admin/api/settings/test-gotify

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Tests the Gotify notification connection. Requires system.settings permission.

```json
{
  "url": "https://gotify.example.com",
  "token": "your-gotify-app-token"
}
```

```json
{
  "success": true,
  "message": "Test notification sent successfully",
  "gotify_message_id": 123
}
```

--------------------------------

### POST /admin/api/keys/create

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Creates a new API key. Requires apikey.create permission.

```json
{
  "name": "My Integration",
  "scopes": ["games:read", "requests:write"],
  "expires_at": "2025-12-31T23:59:59Z"
}
```

```json
{
  "success": true,
  "message": "API key created successfully. Save this key securely - you won't see it again!",
  "key": "ggr_abc123...",
  "id": 1,
  "prefix": "ggr_abc",
  "created_at": "2025-01-05T12:00:00Z"
}
```

--------------------------------

### Configure .env Settings

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/QUICKSTART.md

Required environment variables for the application, including user IDs, database credentials, and IGDB API keys.

```bash
# Set your timezone and user IDs (optional but recommended)
PUID=1000           # Your user ID (run: id -u)
PGID=1000           # Your group ID (run: id -g)
TZ=America/New_York # Your timezone

# Database password (change from default!)
POSTGRES_PASSWORD=your_secure_password_here

# IGDB API (get from Twitch Developer Console)
IGDB_CLIENT_ID=your_igdb_client_id
IGDB_CLIENT_SECRET=your_igdb_client_secret

# Session security (generate a random 32+ character string)
SESSION_SECRET=generate_random_32_character_string_here

# Choose authentication method: basic, oidc, oidc_generic, or authentik
# (the last three are equivalent and all select OIDC/SSO)
AUTH_METHOD=basic
```

--------------------------------

### GET /api/games/{id} Response

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Returns detailed information for a specific game identified by its IGDB ID.

```json
{
  "success": true,
  "game": {
    "igdb_id": "72129",
    "title": "The Legend of Zelda: Breath of the Wild",
    "summary": "Step into a world of discovery...",
    "cover_url": "https://images.igdb.com/igdb/image/upload/t_cover_big/co1nqg.jpg",
    "screenshots": [
      "https://images.igdb.com/igdb/image/upload/t_screenshot_big/sc1234.jpg"
    ],
    "videos": [
      {
        "video_id": "vNuOLHNR1bw",
        "name": "Official Trailer"
      }
    ],
    "platforms": ["Nintendo Switch", "Wii U"],
    "genres": ["Adventure", "Role-playing (RPG)"],
    "companies": ["Nintendo"],
    "game_modes": ["Single player"],
    "rating": 97.5,
    "release_date": "2017-03-03",
    "esrb_rating": "E10+",
    "is_mature": false,
    "is_nsfw": false,
    "content_rating": "Everyone 10+: Fantasy Violence, Mild Suggestive Themes"
  }
}
```

--------------------------------

### Run version-upgrade integrity test commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/TESTING.md

Commands to build the old release, perform manual verification, swap to the new working tree, and tear down the environment.

```bash
make test-upgrade-old FROM=v1.2.5   # builds the tagged release via a git worktree
# sign up, create a request/watchlist entry/setting through the UI
make test-upgrade-new               # swaps to this working tree, same database
# check the migration log and re-verify the data
make test-upgrade-down              # tears down and removes the worktree
```

--------------------------------

### Run test suites via npm

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Commands to execute unit, integration, end-to-end, or all tests, as well as generating coverage reports.

```bash
npm run test:unit          # jsdom project: pure functions, components
npm run test:integration   # node project: server modules, mocked fetch
npm run test:e2e           # Playwright; needs `make test-seeded` first
npm run test:all           # all three, in order

npm run test:coverage
```

--------------------------------

### Upgrade Verification CLI Commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/dev-notes/V1.3_FINDINGS.md

Commands used to test the database upgrade process against the v1.2.5 tag.

```bash
make test-upgrade-old FROM=v1.2.5
```

```bash
make test-upgrade-new
```

--------------------------------

### Docker deployment commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CHANGELOG.md

Standard commands for updating and managing Docker deployments.

```bash
docker compose pull
```

```bash
docker compose up -d
```

```bash
docker compose ps
```

--------------------------------

### Upgrade the application using Docker Compose

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/DEPLOYMENT.md

Perform a database backup, pull the latest images, restart containers, and monitor logs for migration errors.

```bash
docker compose exec -T postgres pg_dump -U postgres ggrequestz > backup_pre_upgrade.sql
docker compose pull
docker compose up -d
docker compose logs -f ggrequestz | grep -iE "schema|migration|error"
```

--------------------------------

### Run migration CLI commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/migrations/README.md

Commands to apply pending migrations or check the current migration status.

```bash
npm run db:migrate   # apply everything not yet recorded
npm run db:status    # show applied and pending
```

--------------------------------

### Write end-to-end tests with Playwright

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Example of an E2E test in tests/e2e/ that requires authentication via a helper function.

```javascript
// tests/e2e/homepage.spec.js
import { signIn } from "./helpers.js";

test("shows the library once signed in", async ({ page }) => {
  test.skip(!(await signIn(page)), "instance has no admin yet");
  await expect(page.locator('a[href^="/game/"]').first()).toBeVisible();
});
```

--------------------------------

### Database migration and maintenance commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/DATABASE_SETUP.md

A list of available npm scripts for managing database schema, migrations, and cache maintenance.

```bash
npm run db:init
npm run db:migrate
npm run db:status
npm run db:warm
npm run db:stats
npm run db:fix
```

--------------------------------

### Run project verification commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/CONTRIBUTING.md

Execute these commands to ensure your changes pass linting, type checking, and unit/integration tests before submitting a pull request.

```bash
npm run lint
npm run check
npm run test:unit
npm run test:integration
```

--------------------------------

### Test Execution Commands

Source: https://github.com/xtreemmak/ggrequestz/blob/main/src/tests/README.md

Available npm scripts for running different test suites and utilities.

```bash
npm run test:unit          # jsdom project
npm run test:integration   # node project
npm run test:e2e           # Playwright, needs the stack up
npm run test:all           # all three, in order

npm run test:watch
npm run test:ui
npm run test:coverage
```

--------------------------------

### POST /admin/api/settings/content-filters

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Configures global content filters. Requires system.settings permission.

```json
{
  "max_esrb_rating": "T",
  "custom_content_blocks": ["violence", "gambling"],
  "excluded_genres": ["Horror"],
  "banned_games": [12345, 67890]
}
```

```json
{
  "success": true,
  "message": "Global content filters saved successfully",
  "filters": { ... }
}
```

--------------------------------

### POST /admin/api/settings/update

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Updates system settings. Requires system.settings permission.

```json
{
  "settings": {
    "setting_key": "value",
    "another_setting": "value"
  }
}
```

```json
{
  "success": true,
  "updated_settings": ["setting_key", "another_setting"],
  "updated_count": 2
}
```

--------------------------------

### Run seed-app.sh script

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/TESTING.md

Executes the seeding script to create the admin user against a running stack.

```bash
./scripts/testing/seed-app.sh
```

--------------------------------

### POST /admin/api/settings/test-romm

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Tests the ROMM server connection. Requires system.settings permission.

```json
{
  "server_url": "https://romm.example.com",
  "username": "admin",
  "password": "password"
}
```

```json
{
  "success": true,
  "message": "ROMM connection successful",
  "total_games": 1500,
  "server_info": {
    "url": "https://romm.example.com",
    "authenticated": true
  }
}
```

--------------------------------

### POST /admin/api/settings/update

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/API.md

Update system settings. Requires system.settings permission.

```APIDOC
## POST /admin/api/settings/update

### Description
Update system settings. Requires system.settings permission.

### Method
POST

### Endpoint
/admin/api/settings/update

### Request Body
- **settings** (object) - Required - Key-value pairs of settings to update

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **updated_settings** (array) - List of updated keys
- **updated_count** (integer) - Number of settings updated
```

--------------------------------

### Set PUID and PGID in .env

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/CONFIGURATION.md

Use these commands to set the correct user and group IDs in your .env file to resolve permission denied errors.

```bash
PUID=$(id -u)
PGID=$(id -g)
```

--------------------------------

### Configure external PostgreSQL connection variables

Source: https://github.com/xtreemmak/ggrequestz/blob/main/docs/setup/DATABASE_SETUP.md

Set these environment variables to point the application to an external PostgreSQL server instead of the default Docker service.

```bash
POSTGRES_HOST=db.internal.example.com
POSTGRES_PORT=5432
POSTGRES_DB=ggrequestz
POSTGRES_USER=ggrequestz
POSTGRES_PASSWORD=...
```