Gameyfin

Gameyfin is a self‑hosted, open‑source platform for managing video game libraries. It exposes a modern web UI that allows users to scan, catalogue, and share games across devices, while providing robust developer hooks for automation, integration, and customization. Built on Kotlin and the JVM ecosystem, Gameyfin leverages a micro‑service–like architecture: a Spring Boot 3 backend that serves RESTful endpoints and a Vaadin Hilla/React hybrid frontend that consumes those APIs. The application is intentionally lightweight—running in a single Docker container or on any JVM‑enabled host—yet it supports advanced features such as OAuth2/OIDC authentication, theming, and a plugin framework powered by PF4J.

Technical Stack & Architecture

• Backend – Spring Boot 3, Kotlin, JPA/Hibernate with an embedded H2 database for persistence. The backend exposes a REST API that the frontend consumes, and it also hosts optional WebSocket endpoints for real‑time updates (e.g., library scan progress).
• Frontend – Vaadin Hilla, which bridges the backend and React components. The UI is a single‑page application that dynamically renders game metadata, themes, and user settings. Hilla’s “lightweight” approach means the browser only downloads a small JavaScript bundle, with server‑side rendering for SEO and performance.
• Plugin System – PF4J (Plug‑In Framework for Java) allows developers to extend Gameyfin with custom modules. Plugins can hook into lifecycle events (e.g., before/after a library scan), add new REST endpoints, or inject UI components. The plugin API is versioned and documented in the repo’s docs/ folder.
• Database – H2 (in‑memory or file‑based) is used for simplicity and zero‑config deployment. For production, the application can be pointed at any JDBC source (PostgreSQL, MySQL) by overriding the Spring Data properties.
• Containerization – The official image (ghcr.io/gameyfin/gameyfin) is built on Alpine‑based JDK 21, ensuring a small footprint (~70 MB). The Dockerfile uses multi‑stage builds to keep the runtime image lean and removes unnecessary build tools.

Core Capabilities & Developer APIs

These APIs are fully typed in Kotlin on the server side and reflected in the Hilla generated TypeScript client, ensuring type safety across the stack.

Deployment & Infrastructure

• Self‑Hosting – A single Docker container is sufficient. Expose port 8080 (or configure via env vars). Persist the /data volume for H2 files and uploaded game binaries.
• Scalability – While Gameyfin is designed as a single‑instance service, its stateless REST API and externalizable database make it trivially deployable behind a load balancer or in a Kubernetes cluster. Horizontal scaling is supported by sharing the same database and file storage (e.g., NFS, S3-compatible object store).
• Resource Footprint – Minimal CPU (0.5 vCPU) and memory (512 MiB) are enough for a small household library. Larger libraries benefit from dedicated storage and optional external DBs.

Integration & Extensibility

• Plugins – Implement a PF4J plugin, bundle it as a JAR, and drop it into /plugins. Gameyfin auto‑discovers and loads it on startup.
• OAuth2/OIDC – Integrate with existing identity providers (Keycloak, Auth0) by configuring application.yml. The plugin system can also expose custom authentication providers.
• Webhooks & Callbacks – Register webhook URLs in the admin UI; Gameyfin will POST JSON payloads on events such as GameAdded or ScanCompleted.
• Custom Themes – The UI supports CSS variables; developers can ship theme bundles as plugins that override default styles, including color‑blind friendly palettes.

Developer Experience

• Documentation – The repo’s docs/ folder contains a comprehensive developer guide, API reference, and plugin development tutorial. Markdown files are kept up‑to‑date with the codebase.
• Community – The project is actively maintained on GitHub, with an issue tracker and a dedicated Discord channel for real‑time support. Contributions are welcomed; the codebase follows Kotlin conventions and is heavily tested with JUnit5.
• Configuration – All major settings are exposed as environment variables or application.yml entries, making CI/CD pipelines straightforward.

Use Cases

1. Home Media Server – Combine Gameyfin with Plex or Jellyfin for a unified media + game catalog.
2. Game Development Teams – Host internal builds, share with QA, and track build usage via