RetroDB

• routes/games.py Decomposition — Split the 2 472-line routes/games.py by extracting shared query helpers and the HLTB sub-API into dedicated modules. No behavior change — all 30 pytest cases still pass, ruff clean.
• services/game_query.py (new) — Extracted query helpers used across the games blueprint: escape_like (SQL LIKE character escaping), _get_filter_options (60-second TTL cache for dropdown values), _build_games_query (the master WHERE/JOIN builder with filter, search, letter-nav, and source-source logic), get_retroachievements_info, get_trophy_info_for_game, get_bonus_discs_for_game. Also extracted the filter cache state and invalidate_filter_cache().
• routes/games_hltb.py (new blueprint) — Extracted the four HLTB API endpoints (/api/hltb-lookup/<id>, /api/hltb-save/<id>, /api/hltb-clear/<id>, /api/hltb/search) into their own blueprint. URL paths are unchanged; endpoint names are now games_hltb.* (no template references needed updating since these are called from JS via fetch).
• routes/games.py shrinks — Down from 2 472 to 2 000 lines (−19%). Combined with v2.77.8, app.py + routes/games.py have together dropped by about 1 450 lines, replaced by six cohesive service/blueprint modules totalling 1 540 lines — the codebase is cleaner to navigate without growing.

RetroDB

Retro Gaming ROM Library Manager - A web-based application for organizing, scraping metadata, and managing your retro game ROM collection.

Status: Solo-developed; releases on a best-effort cadence. See SECURITY.md for the security disclosure policy and CONTRIBUTING.md for the developer setup.

Features

Library & Metadata

• Multi-System Library - Supports 150+ gaming platforms from Atari 2600 to PS5
• Hybrid Metadata Scraping - Combines data from TheGamesDB, IGDB, RAWG, ScreenScraper, and ES-DE gamelists
• AI Fill - Intelligent metadata gap-filling using Gemini, OpenAI, or Claude
• Multi-Rating System - 8 international age rating systems (ESRB, PEGI, CERO, USK, ACB, FPB, GRAC, ClassInd) with cross-mapping
• Bulk Operations - Bulk scraping, bulk editing, compare games, and queue management with job recovery

Achievements & Trophies

• RetroAchievements Integration - Track achievement progress across retro games
• Steam Achievements - Import Steam library and track achievement progress
• Xbox Achievements - Import Xbox library and track gamerscore
• PS3/PSN Trophy Tracking - RPCS3 local trophies and PSN API trophy sync

Organization

• Collections - Tags, named lists with drag-and-drop ordering, and wishlist
• Collector Trophies - Gamification system with milestone-based trophy unlocks
• Game Imports - Import from CLZ Games (PDF), Steam, Xbox, and PlayStation Network

Tools & Analytics

• ROM Tools - Archive scanner, CHD converter/verifier, duplicate finder, multi-disc organizer
• ROM Reports - Naming validation and standards compliance checking
• Analytics Dashboard - 12-tab analytics with charts, export (PNG/CSV), and leaderboards
• Image Standardization - AI upscaling (Real-ESRGAN) and Lanczos downscaling
• Museum - Interactive gaming system encyclopedia with AI-generated content

UI & System

• 7 Themes - Cyberpunk, Matrix, Amber, Ocean, Cathedral (christian internal key), Blade Runner, and Elite (vector starfield) with animated canvas effects
• Multi-User Support - Role-based access control (admin, editor, viewer)
• How Long to Beat - Playtime estimates for your games
• Log Viewer - Unified log browser across all categories
• Genre Normalization - Automatic normalization with custom rules

Quick Start

End users: download the source ZIP from Releases and follow the steps below. Developers: git clone the repo and see CONTRIBUTING.md for the dev setup instead.

1. Extract

Extract the RetroDB ZIP to a directory of your choice.

2. Install

python install.py

This installs Python dependencies, creates config files from templates, and sets up required directories.

3. Launch

# Linux/macOS
./start.sh

# Windows
start.bat

# Or directly
python app.py

Open your browser to http://localhost:5000 and follow the setup wizard.

Requirements

• Python 3.10 or higher (CI tests on 3.12 and 3.13)
• pip (Python package manager)
• Web Browser (Chrome, Firefox, Safari, Edge)

Optional Tools (for ROM Tools features)

• 7-Zip (p7zip-full) - Archive extraction
• unrar - RAR archive support
• chdman (mame-tools) - CHD conversion and verification

Configuration

RetroDB uses two configuration files:

• config.py - Main settings (paths, API keys, server config). Created from config.example.py during install.
• data/settings.json - User-editable settings changed via the web UI.

Most settings can be configured through the web interface at Settings or during the first-run Setup Wizard.

API Keys (Optional)

For metadata scraping and features, you can configure API keys for:

Platform Support

RetroDB runs on Linux, Windows, and macOS. Platform-specific launchers are included:

Deployment

The default start.sh / start.bat / start.command launchers bind RetroDB to localhost — fine for single-machine use. If you want to access RetroDB from other devices on your LAN, follow the reverse-proxy guide in docs/PROXY-DEPLOY.md. Putting RetroDB directly on a non-localhost interface without a proxy in front of it is unsupported.

Updating

1. Back up your install. Three things to copy:
   • database/ — the live SQLite DB lives here (database/roms.db).
   • data/ — settings (settings.json, scraper_settings.json, rom_tools_config.json, psn_tokens.json, xbox_tokens.json, .secret_key).
   • config.py — at the project root; copy it separately.
2. Extract the new version over the existing installation
3. Run python install.py to install any new dependencies
4. Your database and settings will be preserved

Support development

RetroDB is free and open source. If it saves you time, consider tipping — every bit helps keep solo development sustainable.

• GitHub Sponsors: github.com/sponsors/milnet01

(Additional donation surfaces — Patreon, Buy Me A Coffee — are linked from .github/FUNDING.yml as they come online.)

License

RetroDB is released under the MIT License.

Legal

System logos and platform names are trademarks of their respective owners. RetroDB is not affiliated with any console manufacturer or game publisher. See LEGAL.md for full details.

RetroDB does not distribute or host ROM files.

Credits

• Built with Flask and Waitress
• Metadata from TheGamesDB, IGDB, RAWG, ScreenScraper
• Achievement data from RetroAchievements, Steam, Xbox
• Trophy data from PlayStation Network and RPCS3
• AI metadata via Google Gemini, OpenAI, Anthropic Claude
• Playtime data from HowLongToBeat
• Image upscaling via Real-ESRGAN (ONNX Runtime)