ModGallery 🎮

ModGallery ist eine Web- und Desktop-Anwendung, mit der du Mods für deine Spiele sammeln, organisieren und beschreiben lassen kannst. Statt dutzende Mod-Seiten und Readme-Dateien im Kopf zu behalten, bekommst du eine zentrale Übersicht mit Bildern, Versionen, Abhängigkeiten und einer von einer KI erzeugten Zusammenfassung pro Mod. Die Software wurde vollständig mit KI generiert.

Was macht ModGallery? 🤔

• Du legst Spiele an (z.B. "Skyrim") und gibst ihnen optional ein Theme-Bild und eine Farbe. Wählst du ein Spiel im Menü aus, färbt sich die ganze Oberfläche passend dazu ein. 🎨
• Für jedes Spiel legst du Mods an, inklusive Provider (Nexus Mods oder eine lokale HTML-Datei), Quelle, Bildern, Versionsdateien (ZIP) und Abhängigkeiten zu anderen Mods.
• Per Knopfdruck holt sich ModGallery die Original-Beschreibung des Mods und lässt sie von einer LLM (z.B. über OpenRouter oder Ollama) zu einer sauberen, kurzen Zusammenfassung umschreiben.
• Eine Mod-Galerie-Ansicht zeigt jeden Mod wie eine kleine Produktseite an: Bilder, Zusammenfassung, Tags, Abhängigkeiten und herunterladbare Versionen.

Screenshots 📸

Funktionen ✨

• Spiele-Verwaltung: Spiele anlegen, mit Farbe und Theme-Bild versehen. Die Top-3-Farben des Bildes werden automatisch erkannt und als App-Theme verwendet.
• Mods anlegen: einzeln über ein Formular, oder in großer Zahl über einen Datei-Import (aktuell im "Mod Organizer"-Format).
• Automatische Zusammenfassung: Mod-Beschreibungen werden per Provider geladen und per LLM zu einer kurzen, verständlichen Zusammenfassung umgeschrieben - inklusive Bearbeiten der erzeugten Zusammenfassung direkt in der Oberfläche.
• Mod-Galerie: Bilder-Viewer, Chips für Provider/LLM/Spiele/Kategorien, Abhängigkeiten und Versions-Downloads für jeden Mod.
• Suche, Filter & Sortierung: Mods nach Titel durchsuchen, nach Provider/LLM/Kategorie filtern und jede Spalte sortieren.
• Massenbearbeitung: mehrere Mods gleichzeitig auswählen, Zusammenfassung erzeugen, bearbeiten oder löschen.
• Kategorien & Abhängigkeiten: Mods frei mit Kategorien taggen und Abhängigkeiten zu anderen Mods (optional an eine bestimmte Version gepinnt) hinterlegen.
• Zwei Provider: Nexus Mods über die offizielle API, oder eine selbst hochgeladene lokale HTML-Datei für Seiten ohne API-Zugriff.
• Zwei LLM-Backends: OpenRouter oder eine eigene Ollama-Instanz.
• Läuft als Web-App oder als natives Windows-Programm (siehe Desktop-App), ganz ohne dass Python oder Node installiert sein müssen.

Technologien 🛠️

Backend

• Python 3.14
• FastAPI
• SQLite
• Swagger / ReDoc (automatische API-Dokumentation)

Frontend

• React 19
• MUI (Material UI)
• Vite

Desktop

• Tauri (Rust) mit gebündeltem Python-Backend als Sidecar

Aufbau 🧱

ModGallery besteht aus zwei Teilen, die über run.py gemeinsam gestartet werden:

• Api: Eine FastAPI-Anwendung unter dem URL-Pfad /api/v1, die die SQLite-Datenbank verwaltet und die Mod-/Spiel-Assets (Bilder, Beschreibungen, Versions-ZIPs) auf der Festplatte ablegt.
• Frontend: Eine React-Anwendung, die unter dem Root-Pfad ausgeliefert wird und die komplette Bedienoberfläche darstellt.

Installation ⚙️

• Umgebungsvariable PROVIDER_NEXUS_SECRET mit deinem Nexus Mods API-Key setzen.
• Umgebungsvariable LLM_OPENROUTER_SECRET mit deinem OpenRouter API-Key setzen.
• Optional: DB_PATH und MODS_DIR setzen, um den Speicherort der SQLite-Datenbank bzw. des Mods-Ordners zu ändern. Ohne diese Variablen werden die Standardpfade im Api-Ordner verwendet (db.sqlite3 und Mods).

Quickstart 🚀

python run.py

Startet API und Frontend gemeinsam für den produktiven Einsatz. Mit Strg + C beenden.

Docker 🐳

Ein einzelnes Dockerfile im Projekt-Root baut das Frontend und startet die API zusammen in einem Container. Die API liefert dabei sowohl das gebaute Frontend als auch die /api/v1-Endpunkte über denselben Prozess auf Port 8000 aus.

Image bauen:

docker build -t modgallery .

Container starten (Secrets durch deine eigenen ersetzen):

docker run -d --name modgallery -p 8000:8000 -e PROVIDER_NEXUS_SECRET=dein-nexus-secret -e LLM_OPENROUTER_SECRET=dein-openrouter-secret -v modgallery-mods:/app/Api/Mods -v modgallery-games:/app/Api/Games modgallery

Danach http://localhost:8000 im Browser öffnen.

Desktop-App (Windows) 🖥️

ModGallery gibt es auch als native Windows-Anwendung auf Basis von Tauri. Das React-Frontend läuft dabei in einem nativen Fenster (WebView2), das Python-Backend wird als gebündelter "Sidecar"-Prozess mitgeliefert - die Endnutzer:innen brauchen also weder Python noch Node noch einen Browser.

• Die SQLite-Datenbank und die Mods-/Games-Ordner werden beim ersten Start neben der .exe angelegt. Die App ist dadurch komplett portabel.
• Installiert wird pro Benutzer nach %LOCALAPPDATA%\ModGallery, also ohne Administratorrechte.
• Beim ersten Start fragt die App nach den beiden API-Keys (Nexus Mods und OpenRouter) und speichert sie Base64-codiert in einer api.json neben der .exe. Sind die gleichnamigen Umgebungsvariablen gesetzt, haben sie weiterhin Vorrang.

Tests ✅

Die API hat eine automatisierte Testsuite (pytest) unter Api/tests. Sie läuft komplett offline gegen eine SQLite-Wegwerf-Datenbank und temporäre Asset-Ordner, braucht also weder API-Keys noch Internetzugang:

pip install -r Api/requirements-dev.txt
python -m pytest

(ausgeführt mit dem Api-Ordner als Arbeitsverzeichnis).

Datenbank 🗄️

Die Konfiguration wird in einer SQLite-Datenbank (db.sqlite3) gespeichert, die automatisch beim ersten Start angelegt wird. Die wichtigsten Tabellen:

Tabelle	Beschreibung
games	Die angelegten Spiele, inklusive Farbe und Theme-Bild.
categories	Frei vergebbare Kategorien, mit denen Mods getaggt werden können.
mods	Die eigentlichen Mods mit Provider, Quelle, verwendeter LLM und Asset-Ordner.
mod_games / mod_categories	Verknüpft Mods vielfach mit Spielen bzw. Kategorien.
mod_dependencies	Abhängigkeiten zwischen Mods, optional an eine Version gepinnt.
mod_versions / mod_images	Hochgeladene Versions-ZIPs bzw. Bilder je Mod.
providers	Konfigurierte Provider (z.B. Nexus Mods) samt Secret.
llms	Konfigurierte LLMs (Name, URL, Modell, System-Prompt, Secret).

Mehr Details findest du im Repository unter Api/API.md.