whattoplay/ARCHITECTURE.md

WhatToPlay - Architektur Entscheidung

Problem: Gaming Platform APIs für iOS/Web

Services Status:

• ✅ Steam: Öffentliche Web API (GetOwnedGames) - funktioniert im Browser/iOS
• ⚠️ GOG: Galaxy Library API - benötigt OAuth (Server-Side Token Exchange)
• ❌ Epic Games: Keine öffentliche API - nur über Legendary CLI (Python)
• ❌ Amazon Games: Keine öffentliche API - nur über Nile CLI (Python)

Warum CLI-Tools nicht funktionieren:

❌ Python/Node CLI Tools (Legendary, Nile, gogdl)
   └─> Benötigen native Runtime
   └─> Funktioniert NICHT auf iOS
   └─> Funktioniert NICHT im Browser
   └─> Funktioniert NICHT als reine Web-App

Lösung: Hybrid-Architektur

Phase 1: MVP (Jetzt)

Frontend (React/Ionic)
   ↓
Steam Web API (direkt)
   - GetOwnedGames Endpoint
   - Keine Auth nötig (nur API Key)
   - Funktioniert im Browser

Phase 2: GOG Integration (wenn Backend da ist)

Frontend (React/Ionic)
   ↓
Backend (Vercel Function / Cloudflare Worker)
   ↓
GOG Galaxy API
   - OAuth Token Exchange (Server-Side)
   - Library API mit Bearer Token
   - CORS-Safe

Phase 3: Epic/Amazon (Zukunft)

Option A: Backend Proxy

Frontend → Backend → Epic GraphQL (Reverse-Engineered)
                  → Amazon Nile API

Option B: Manuelle Import-Funktion

User exportiert Library aus Epic/Amazon
   ↓
User uploaded JSON in App
   ↓
App parsed und zeigt an

Aktuelle Implementation

Steam (✅ Funktioniert jetzt)

// fetch-steam.mjs
const response = await fetch(
	`http://api.steampowered.com/IPlayerService/GetOwnedGames/v0001/`,
	{ params: { key, steamid, format: "json" } },
);

GOG (⚠️ Vorbereitet, braucht Backend)

// Jetzt: Manueller Token aus Browser DevTools
// Später: OAuth Flow über Backend
const response = await fetch(
	`https://galaxy-library.gog.com/users/${userId}/releases`,
	{ headers: { Authorization: `Bearer ${token}` } },
);

Epic/Amazon (❌ Placeholder)

// Aktuell: Leere JSON-Dateien als Platzhalter
// Später: Backend-Integration oder manuelle Import-Funktion

Deployment Strategie

Development (macOS - Jetzt)

npm run fetch    → Lokale Node.js Scripts holen Daten
npm run dev      → Vite Dev Server mit Hot Reload

Production (iOS/Web - Später)

Frontend: Vercel/Netlify (Static React App)
Backend:  Vercel Functions (für GOG OAuth)
Data:     Supabase/Firebase (für User Libraries)

Nächste Schritte

1. ✅ Steam: Fertig implementiert
2. 🔄 GOG: Manuelle Token-Eingabe (Development)
3. 📝 Epic/Amazon: Placeholder JSON
4. 🚀 Backend: OAuth-Service für GOG (Vercel Function)
5. 📱 iOS: PWA mit Service Worker für Offline-Support

Wichtige Limitierungen

• Keine nativen CLI-Tools in Production
• CORS blockiert direkte Browser → Gaming APIs
• OAuth Secrets können nicht im Browser gespeichert werden
• Backend ist Pflicht für GOG/Epic/Amazon

---

Fazit: Für iOS/Web müssen wir ein Backend bauen. Steam funktioniert ohne Backend, GOG/Epic/Amazon brauchen Server-Side OAuth.