## 1. Projektübersicht

"Projekt Chimera" ist ein hybrides Krimi-Dinner-Erlebnis, das physische soziale Interaktion mit einer digitalen App-Komponente verbindet. Das Alleinstellungsmerkmal ist der Einsatz einer zweistufigen KI-Architektur, die nicht nur einzigartige narrative Szenarien generiert, sondern diese auch proaktiv auf logische Konsistenz validiert und korrigiert.

Die Architektur basiert auf einer klaren Trennung: Supabase dient als dedizierter Service für die Benutzerauthentifizierung, während alle Spieldaten (Szenarien, Spieler, Spielstände) in einer separaten, dedizierten PostgreSQL-Datenbank gehostet werden. Ein zentrales FastAPI-Backend fungiert als sichere Schnittstelle zwischen den Clients und beiden Diensten.

## 2. Narratives Design & Validierung

Die Generierung jedes Spiels folgt einem strengen, zweistufigen Prozess, um die narrative Qualität und logische Integrität zu gewährleisten.

### Schritt 1: Kreative Generierung (Der "Autor")

In dieser Phase agiert die KI als kreativer Autor. Sie erhält einen umfassenden Prompt, der die gewünschten Rahmenbedingungen (Szenario-Beschreibung, Rundenanzahl) vorgibt. Die genaue Spieleranzahl wird dynamisch aus der Lobby übernommen, kurz bevor die KI die Generierung startet.

- Hintergrundgeschichte: Der Rahmen des Geschehens und der Grund für das Zusammentreffen.
- Charaktere: Detaillierte Rollen mit Persönlichkeit, Beziehungen und öffentlichen Informationen.
- Geheimnisse & Ziele: Private Geheimnisse und spielrelevante Ziele für jeden Charakter.
- Der Mord & lückenloser Zeitstrahl: Definition des Verbrechens und Etablierung eines kontinuierlichen Zeitstrahls für jeden Charakter (z.B. "16:30-16:45: Aktion A"), um Alibis nachvollziehbar zu machen.
- Beziehungsgeflecht: Eine Matrix der komplexen Beziehungen zwischen allen Charakteren.
- Hinweise: Ein Set von Hinweisen, die den Mörder belasten oder falsche Fährten legen, aufgeteilt auf die gewählte Rundenanzahl.

### Schritt 2: Logische Validierung & Korrektur (Der "Logik-Lektor")

Der rohe Output aus Schritt 1 wird nun an eine zweite KI-Instanz übergeben, die als akribischer Logik-Lektor agiert. Die KI wird instruiert, das gesamte Szenario anhand einer Checkliste von potenziellen Fehlern zu überprüfen:

- Widersprüche in Zeitlinien: Passen Alibis und die Zeitblöcke auf den Zeitstrahlen aller Charaktere lückenlos und widerspruchsfrei zusammen?
- Motiv-Konsistenz: Ist das Motiv des Mörders stark genug und logisch begründet?
- Hinweis-Validität: Führt mindestens ein entscheidender Hinweis logisch zum Täter? Sind falsche Fährten subtil?
- Charakter-Konsistenz: Handeln die Charaktere gemäß ihrer beschriebenen Persönlichkeit und Ziele?
- Regelkonformität: Ist das Spiel fair und lösbar?

Die KI korrigiert gefundene Fehler minimalinvasiv, um die kreative Essenz nicht zu verändern, und gibt ein logisch wasserdichtes Spielszenario aus.

## 3. Technische Architektur

Die Architektur ist auf maximale Kontrolle und Skalierbarkeit ausgelegt. Die React Native-Clients kommunizieren ausschließlich mit dem FastAPI-Backend. Supabase wird als reiner Authentifizierungs-Provider genutzt. Echtzeit-Updates werden über eine WebSocket-Verbindung vom FastAPI-Server an die Clients gepusht.

                            graph TD
                                subgraph "Spieler-Geräte"
                                    P1["React Native Apps"]
                                end

                                subgraph "Authentifizierung"
                                    Auth["Supabase Auth"]
                                end

                                subgraph "Sicheres Backend"
                                    FastAPI["FastAPI Server
     REST & WebSockets"]
                                end

                                subgraph "Spieldaten-Bank"
                                    PG_DB["PostgreSQL DB"]
                                end

                                subgraph "Externe Dienste"
                                    OAI["OpenAI API"]
                                end

                                %% Verbindungen
                                P1 -- "1. Login" --> Auth
                                P1 -- "2. API Calls (mit Token)" --> FastAPI

                                FastAPI -- "3. KI Call" --> OAI
                                FastAPI -- "4. DB-Zugriff" --> PG_DB

                                FastAPI -- "5. WebSocket Updates" --> P1

### Datenfluss-Beschreibung:

1. Authentifizierung: Der Benutzer authentifiziert sich in der React Native-App direkt bei Supabase Auth. Die App erhält ein JWT (JSON Web Token).
2. API-Anfragen: Für alle spielrelevanten Aktionen sendet die App eine Anfrage an den FastAPI-Server und fügt das JWT von Supabase in den Authorization-Header ein. FastAPI validiert dieses Token.
3. KI-Generierung: Für die Spielerstellung ruft der FastAPI-Server die OpenAI-API auf.
4. Datenbank-Interaktion: FastAPI ist die einzige Komponente, die mit der dedizierten PostgreSQL-Datenbank kommuniziert.
5. Echtzeit-Updates: Die Clients bauen eine WebSocket-Verbindung zum FastAPI-Server auf. Bei Änderungen pusht der Server Updates an alle verbundenen Clients.

## 4. User Interface (UI) Konzept

Die UI-Konzepte werden als klare, moderne Wireframes visualisiert, um den gesamten App-Flow von der Erstellung bis zum Spiel darzustellen.

### 1. Login

#### PROJEKT CHIMERA

Noch kein Konto? Jetzt registrieren

### 2. Registrierung

#### Konto erstellen

Bereits ein Konto? Zum Login

### 3. Home Dashboard

#### Deine Spiele

Tech-Konferenz 2035

Status: Aktiv (Runde 2/3)

Villa Vendetta

Status: Lobby (0 Spieler)

### 4. Spiel erstellen (Host)

#### Neues Spiel erstellen

Szenario-Beschreibung
Rundenanzahl
3

Die Spieleranzahl ist flexibel (mind. 3 Spieler) und wird in der Lobby durch die Anzahl der beigetretenen Spieler bestimmt.

### 5. Host-Lobby

Spiel-Lobby

#### Tech-Konferenz 2035

Teile diesen Code mit deinen Mitspielern:

GHY-781

##### Beigetretene Spieler (3)

- Maria
- Jonas
- Sandra

### 6. Spieler-Ansicht (Rolle)

Deine Rolle

#### Dr. Aris Thorne

##### Deine Ziele:

- Finde heraus, wer deine Forschung sabotiert hat.
- Verhindere, dass dein Geheimnis über das gescheiterte Experiment ans Licht kommt.

##### Deine Geheimnisse:

Du hast vor einem Monat bei einem nicht genehmigten Experiment die Stromversorgung der Station überlastet, was zu einem kritischen Ausfall führte. Nur das Opfer wusste davon.

### 6. Spieler-Ansicht (Hinweise)

Deine Rolle

#### Dr. Aris Thorne

##### Runde 2 (18:00 - 19:00 Uhr)

HINWEIS #3

Ein zerrissener Brief wurde gefunden. Die Worte "Schulden" und "letzte Warnung" sind lesbar.

##### Runde 1 (16:00 - 18:00 Uhr)

HINWEIS #1

Das Opfer wurde mit einem schweren Gegenstand erschlagen.

### 7. Spieler-Ansicht (Charaktere)

Deine Rolle

#### Dr. Aris Thorne

Evelyn Reed (CEO)

Die ehrgeizige CEO des Konkurrenzunternehmens. Es ist bekannt, dass sie und das Opfer eine erbitterte Rivalität pflegten.

Ivan Petrov (Sicherheitschef)

Der loyale, aber jähzornige Sicherheitschef. Er war für den Schutz des Opfers verantwortlich.

### 7. Spieler-Ansicht (Zeitstrahl)

Deine Rolle

#### Dr. Aris Thorne

##### Dein persönlicher Zeitstrahl

16:30 - 16:45 Uhr

Streitgespräch mit dem Opfer im Labor.

16:45 - 17:00 Uhr

Alleine im Büro, E-Mails beantwortet.

17:00 - 17:20 Uhr

Gespräch mit Ivan Petrov in der Cafeteria. (Dein Alibi)

ca. 17:30 Uhr (TODESZEITPUNKT)

### 8. Auflösung

#### Der Mörder war...

Ivan Petrov!

Sein Motiv war Rache, da das Opfer ihn erpresst hat. Die Mordwaffe war ein schwerer Schraubenschlüssel aus dem Werkzeugraum.

##### Abstimmungsergebnis

- Du hast für Evelyn Reed gestimmt.
- Maria hat für Ivan Petrov gestimmt. (Korrekt!)
- Jonas hat für Sandra gestimmt.

### 9. Host Notfall-Dashboard

#### Host Notfall-Dashboard

Spoiler-freie Steuerung (im Spiel)

##### Spiel-Steuerung

##### Experten-Optionen

Achtung: Generiert nur die Hinweise für die AKTUELLE Runde neu. Nur nutzen, wenn Hinweise fehlerhaft wirken.

##### Gefahrenzone

Beendet das Spiel für alle und startet die Lobby neu.

## 5. API-Endpunkte & Datenbank-Interaktion

### FastAPI-Backend (erweitert)

Das Backend wird zur zentralen API für die gesamte Spiellogik. Alle Endpunkte erfordern ein gültiges Supabase JWT.

- `POST /game/create`: Erstellt ein neues Spiel, ruft OpenAI auf, speichert in PG_DB.
- `POST /game/{game_code}/join`: Fügt einen Spieler zu einem Spiel hinzu.
- `GET /game/{game_code}/state`: Ruft den aktuellen Zustand eines Spiels ab.
- `POST /game/{game_code}/vote`: Gibt eine Stimme für einen Charakter ab.
- `GET /game/{game_code}/character`: Ruft die Charakterdetails für den authentifizierten Spieler ab.
- `/ws/{game_code}`: WebSocket-Endpunkt für Echtzeit-Updates.

### Client-Interaktionen

- Supabase Auth (`supabase-js`): Wird in der React Native App ausschließlich für Login, Registrierung und die Verwaltung des Auth-Zustands (JWT) verwendet.
- API-Client (z.B. Axios): Wird für alle HTTP-Anfragen an das FastAPI-Backend genutzt.
- WebSocket-Client: Wird verwendet, um die Echtzeit-Verbindung zum `/ws/...` Endpunkt des Backends herzustellen und auf Updates zu lauschen.

## 6. Datenmodelle & `game_data` Detailbeschreibung

Die dedizierte PostgreSQL-Datenbank enthält die gesamte Spiellogik, während Supabase ausschließlich für die Identitätsverwaltung zuständig ist.

### Dedizierte PostgreSQL-Datenbank (Spieldaten)

#### Tabelle: `games`

Spalte | Datentyp | Beschreibung
--- | --- | ---
id | uuid | Eindeutige ID für ein Spiel.
created_at | timestamp | Zeitstempel der Erstellung.
host_id | uuid | Referenz auf die User-ID des Hosts aus Supabase.
game_code | varchar | Kurzer Code zum Beitreten (z.B. "GHY-781"). Indiziert!
status | varchar | Aktueller Status (setup, lobby, active, finished).
game_data | jsonb | Das komplette KI-generierte Szenario.

#### Tabelle: `players`

Spalte | Datentyp | Beschreibung
--- | --- | ---
id | uuid | Eindeutiger Eintrag für einen Spieler in einem Spiel.
game_id | uuid | Verweist auf das zugehörige Spiel in `games`.
player_id | uuid | Referenz auf die User-ID aus Supabase (kann `NULL` sein).
player_name | varchar | Der im Spiel angezeigte Name des Spielers.
character_id | varchar | Verknüpft den Spieler mit seiner Rolle im `game_data`-JSON.

### Die `game_data` (jsonb) Spalte: Der "digitale Spielkarton"

Diese einzelne Spalte ist das narrative Herzstück jedes Spiels. Hier wird das gesamte, von der KI generierte und validierte JSON-Objekt gespeichert.

## 7. Prompt-Engineering-Strategie

### Prompt 1: Der kreative Autor

#### System-Prompt:

Du bist ein preisgekrönter Autor von Kriminalromanen. Deine Aufgabe ist es, ein vollständiges, komplexes und fesselndes Krimi-Dinner-Szenario zu erstellen. Halte dich exakt an die vorgegebene JSON-Struktur.

#### User-Prompt (Beispiel):

Erstelle ein Krimi-Dinner-Szenario für 5 Spieler über 3 Runden. Das Thema lautet: "Ein Mord auf einer Tech-Konferenz im Jahr 2035". Erstelle für jeden Charakter einen lückenlosen Zeitstrahl mit Zeitblöcken (z.B. "16:30-16:45") und verteile die Hinweise logisch auf die Runden. Generiere das vollständige Spiel-JSON und stelle sicher, dass der Mord logisch aufgeklärt werden kann.

### Prompt 2: Der Logik-Lektor

#### System-Prompt:

Du bist ein extrem detailorientierter und logisch denkender Lektor. Deine Aufgabe ist es, das dir vorgelegte Krimi-Szenario auf Widersprüche und Logikfehler zu überprüfen und minimalinvasiv zu korrigieren.

#### User-Prompt:

Hier ist ein JSON-Objekt. Bitte agiere als Logik-Lektor. Überprüfe es auf: Zeitlinien-Konflikte (sind die Zeitstrahlen aller Charaktere widerspruchsfrei?), Motiv-Schwäche, Unlösbarkeit, Inkonsistente Charakter-Aktionen. Gib das vollständige, korrigierte JSON zurück.
[Hier wird das gesamte JSON aus Schritt 1 eingefügt]

## 8. User Journey & Spielablauf

Der Lebenszyklus eines Spiels ist in mehrere Phasen unterteilt, wobei jede Runde einem definierten Zeitfenster entspricht, um den Zeitstrahl zu strukturieren.

1. Phase 0: Generierung & Vorbereitung (`status: setup`)

   Der Host kann ein Spiel generieren, lange bevor es stattfindet. In dieser Phase erhält er den Einladungscode und eine spoiler-freie Übersicht über Thema und Charakter-Namen zur Vorbereitung.

2. Phase 1: Lobby (`status: lobby`)

   Am Tag des Spiels öffnet der Host die Lobby. Die Spieler treten mit dem Code bei. Der Host kann Spieler hinzufügen/entfernen und hat die Option, das Szenario neu zu generieren, bevor er das Spiel startet.

3. Phase 2: Rollenverteilung

   Nach dem Spielstart weist das Backend jedem Spieler eine Rolle zu und sendet die geheimen Informationen an das jeweilige Gerät.

4. Phase 3: Spielrunden (`status: active`)

   Das Spiel verläuft in Runden, die jeweils einem Zeitfenster zugeordnet sind (z.B. Runde 1: 16-18 Uhr). In jeder Runde gibt das System neue Hinweise frei. Spieler können ihren persönlichen Zeitstrahl und alle bisherigen Hinweise einsehen.

5. Phase 4: Abstimmung & Auflösung (`status: finished`)

   Nach der letzten Runde wird die Abstimmung freigeschaltet. Danach folgt die Auflösung, bei der der Mörder und alle Geheimnisse enthüllt werden.

## 9. Geschäftsmodell & Monetarisierung

Die App wird kein kostenloses Basis-Modell anbieten. Die Monetarisierung erfolgt direkt über die Nutzung der Spiunktion.

### Abonnement-Modell

Nutzer zahlen einen monatlichen oder jährlichen Beitrag und erhalten dafür ein festes Kontingent an Spielen (z.B. die Möglichkeit, 2 Spiele pro Woche zu generieren und zu spielen).

### Einmalkauf (Pay-per-Game)

Alternativ zum Abo können Nutzer einzelne Spiele per Einmalkauf freischalten. Dies bietet maximale Flexibilität für Gelegenheitsspieler.

## 10. Skalierbarkeit, Kosten & Fehlerbehandlung

- Kostenkontrolle (OpenAI): Ein Rate-Limiting auf dem `/game/create` Endpunkt verhindert Missbrauch (z.B. nur ein Spiel alle 5 Minuten pro Nutzer).
- Fehlerbehandlung bei Generierung: Schlägt der OpenAI-Call fehl, unternimmt das Backend automatisch 1-2 erneute Versuche, bevor es einen Fehler an den Host meldet.
- Nahtloses Wiederverbinden: Spieler können jederzeit wieder in ein laufendes Spiel einsteigen (z.B. nach Verbindungsabbruch) und erhalten den aktuellen Spielzustand.
- Notfall-Dashboard (Host): Der Host erhält ein simples, spoiler-freies Admin-Panel, um das Spiel zu pausieren, Runden manuell auszulösen oder als Experte die Hinweise einer Runde neu zu generieren. Für katastrophale Fehler gibt es eine Option zum kompletten Neustart des Spiels.

## 11. Rechtliches & Datenschutz

Aufgrund der Verarbeitung von E-Mail-Adressen für die Authentifizierung sind folgende Punkte für den Launch zwingend erforderlich:

- DSGVO-konforme Datenschutzerklärung: Beschreibt, welche Daten zu welchem Zweck verarbeitet werden.
- Impressum: Gesetzlich vorgeschriebene Angabe des Betreibers.
- Löschung des Accounts: Eine einfache Möglichkeit für Nutzer, ihren Account und alle Daten zu löschen.