Retrom

Retrom is a self‑hosted, web‑first service that aggregates a user’s DRM‑free game collection across multiple platforms and emulators. From a technical standpoint, it exposes a RESTful API that drives a lightweight Vue‑based web client and a set of native desktop clients (Windows, macOS, Linux). The core job is to scan a designated filesystem for game binaries, map them to metadata providers, and expose that catalog through an authenticated gateway. Clients can then trigger installation, uninstallation, or launch commands which are forwarded to the server via websocket streams. This design decouples storage from execution, enabling a single machine to act as a cloud‑like hub while clients remain thin.

Architecture

• Backend – Node.js (TypeScript) powered by the Express framework. The server layer is split into a core service that handles filesystem scanning, metadata enrichment, and emulator profile management, and a websocket bridge that streams real‑time events to clients.
• Database – PostgreSQL serves as the primary persistence layer for user accounts, library metadata, and emulator profiles. A small Redis cache is optionally used to accelerate query‑heavy endpoints such as “most played” lists.
• Storage – Games are stored in a configurable directory tree; the server exposes these files via HTTP range requests, allowing partial downloads and streaming.
• Client – Desktop clients are built with Electron (TypeScript) for cross‑platform support. They communicate with the server over HTTPS and websockets, handling local installation manifests and launching via OS‑specific executables.
• Containerization – The entire stack can be packaged as a Docker Compose set of services: api, web, db, and optional redis. The Docker image pulls the latest Node binaries, compiles TypeScript on startup, and seeds a fresh PostgreSQL database.

Core Capabilities

• Library Scanning – Recursive filesystem walk with checksum verification to avoid duplicate entries.
• Metadata API – Integration with Open Game Database (OGDB), RAWG, and custom provider hooks; developers can extend these via a simple plugin interface.
• Emulator Profiles – JSON‑based configuration objects that specify command line flags, environment variables, and launch wrappers per platform. Profiles are stored in the database and can be edited through the web UI or via API endpoints (/api/profiles).
• Remote Execution – REST endpoints /games/:id/install, /games/:id/uninstall, and /games/:id/launch trigger asynchronous jobs handled by a worker queue (BullMQ).
• Webhooks – Optional outgoing webhooks for state changes, enabling integration with external services like Discord bots or home‑automation systems.
• Authentication – JWT‑based auth with optional OAuth2 support for enterprise deployments.

Deployment & Infrastructure

Retrom requires a machine with at least 4 GB RAM and 20 GB of free disk space per terabyte of game data. The Docker image can be run on any platform that supports Docker: Linux servers, Raspberry Pi 4 (ARM64), or even macOS Homebrew. For high‑availability, a Kubernetes deployment can be orchestrated with Helm charts that expose the API via an Ingress controller and use StatefulSets for PostgreSQL persistence. Horizontal scaling is limited by the single‑node nature of the filesystem; however, a distributed object store (e.g., MinIO) can be mounted to share game binaries across multiple API nodes.

Integration & Extensibility

• Plugin System – Developers can drop a .js module into the plugins/ directory; the server loads it at boot, exposing new metadata providers or custom launch hooks.
• API SDKs – A TypeScript client library is available on npm, simplifying integration into custom dashboards or CI pipelines.
• Webhooks & Event Bus – Subscribers can listen to game:installed, game:uninstalled, and launch:start events via HTTP or RabbitMQ.
• Custom UI – The Vue web client is open‑source; developers can fork it, replace the theme, or add new views without touching the backend.

Developer Experience

Configuration is driven by environment variables and a single config.json file, making it trivial to adjust scan paths or API ports. The documentation is comprehensive: a quick‑start guide, full API reference, and plugin tutorials are all hosted on the project's wiki. The community is active on Discord, where developers can request features or report bugs in real time. Licensing under the MIT license removes any commercial barriers, allowing integration into private or public cloud deployments without legal overhead.

Use Cases

1. Home Media Server – A single NAS hosts thousands of emulation ROMs; Retrom exposes them to every device in the house, preserving a unified library.
2. Retro‑Gaming Café – Operators can pre‑install game collections on a shared server and let patrons launch from any kiosk.
3. Educational Labs – Schools can maintain a controlled library of simulation software, with per‑user profiles and usage analytics.
4. Cross‑Platform Development – Game developers test builds on multiple platforms from a single repository, using Retrom’s launch orchestration to automate CI pipelines.

Advantages

• Performance – Native Electron clients and server‑side caching reduce latency compared to cloud services.
• Flexibility – Full control over storage, networking,