managarten/games/worldream/docs/ProjectPlan.md

Projektbericht (kurz) – Personas / Stories

1) Zielbild

Eine text-first Plattform, in der Characters, Objects, Places und Stories als Texte gepflegt werden. Stories kombinieren diese Bausteine über einfache @slug-Referenzen (ohne harte DB-Joins). Fokus: schnell Stories bauen, konsistente Welten darstellen, LLM-freundlich.

2) MVP-Funktionsumfang

• Content-Editor für world|character|object|place|story (ein Formular, gleiche Felder).
• Story-Builder: Auswahl per @slug (z. B. cast=@mira,@timo | places=@neo_station).
• Story-Verlauf (optional, aber empfohlen): Einträge als Narration/Dialog.
• Suche (FTS) über Titel, Summary, Lore, Canon-Facts, Glossar.
• Versionierung (optional): jede Änderung rückrollbar.
• Anhänge (Bilder/Audio/Dokumente) per URL/Storage.

3) Architektur / Tech-Stack

• Frontend: SvelteKit + TypeScript, Tailwind, Form-Editor (MD/Markdown).
• Backend: SvelteKit API Routes (+server.ts), leichte Services.
• DB: Supabase (Postgres) mit Hybrid-Schema: feste Meta-Spalten + content jsonb.
• Auth: Auth.js (oder Lucia).
• Search: Postgres FTS (tsvector Generated Column).
• Storage: Supabase Storage / S3-kompatibel (für Attachments).
• Deploy: Docker (Fly.io/Hetzner/Render), kein Vercel-Lock-in.

4) Datenmodell (vereinfacht)

A) Eine Tabelle für alles (empfohlen)

content_nodes

• Meta: id uuid, kind ('world'|'character'|'object'|'place'|'story'), slug, title, summary, owner_id?, visibility ('private'|'shared'|'public'), tags text[], world_slug?, created_at, updated_at
• Inhalte: content jsonb (siehe Felder unten)
• Suche: search_tsv tsvector GENERATED (aus ausgewählten Textfeldern)

story_entries (Story-Verlauf, optional)

• id, story_slug, position, type ('narration'|'dialog'|'note'), speaker_slug?, body, created_by, created_at

node_revisions (Versionierung, optional)

• id, node_id/slug, content_before jsonb, content_after jsonb, edited_by, edited_at, notes?

attachments (Assets, optional)

• id, node_slug, kind ('image'|'audio'|'doc'), url, notes?, created_at

B) Einheitliche content.json-Schlüssel (für alle Kinds)

• appearance – Beschreibung des Aussehens in Worten
• image_prompt – Prompt für Bildgenerierung
• lore – Vorgeschichte/History/Lore
• voice_style – Tonalität/Erzähl-/Sprechstil
• capabilities – Fähigkeiten/Eigenschaften (Text oder Bulletpoints)
• constraints – Grenzen/No-Gos/Regeln
• motivations – Ziele/Triebe/Konflikte
• secrets – verborgene Infos / Twists
• relationships_text – Beziehungen als Freitext (mit @slug)
• inventory_text – Besitz/Ausrüstung als Text
• timeline_text – Ereignisse/Chronik als Text
• glossary_text – Begriffe/Aliasse/Schreibregeln
• canon_facts_text – „offizielle Wahrheiten/Regeln“
• state_text – aktueller Zustand in Sätzen („Amulett liegt im Tresor …“)
• prompt_guidelines – Anweisungen an LLM (Stil, Person, Perspektive)
• references – freie Referenzen/Quellen (z. B. cast=@mira,@timo)
• _links (optional) – maschinenlesbarer Cache: { cast: ["@mira"], places: ["@neo_station"] }
• _aliases (optional) – alternative Slugs für Umbenennungen
• _i18n (optional) – Übersetzungen pro Sprache

Naming: characters heißen in der DB kind='character'.

5) RLS / Sichtbarkeit

• Owner: Vollzugriff.
• shared: Schreibrechte für eingeladene Kollaborateure, sonst Read.
• public: Read-only.
• Policies leiten sich an owner_id/visibility + optional Project-Team ab.

6) Vor- & Nachteile des Ansatzes

Pro

• Extrem schnell iterierbar; ein Editor für alles.
• LLM-freundlich (reiner Text/Markdown, klare Prompt-Felder).
• Weniger Schema-Migrationen dank JSONB.
• @slug-Referenzen: menschlich & maschinenlesbar.

Contra

• Keine FK-Sicherheit; Slug-Umbenennungen müssen per _aliases abgefedert werden.
• Auswertungen über strukturierte Werte begrenzt (bewusst text-first).
• Konsistenz-Checks geschehen über Textregeln/Parser, nicht DB-Constraints.

Mitigation

• Beim Speichern @slug parsen → _links füllen (Cache).
• node_revisions aktivieren (Rollback).
• search_tsv nur mit relevanten Feldern befüllen (Performance).

7) Minimale API (Beispiele)

• POST /api/nodes – create/update content_nodes
• GET /api/nodes?kind=story&query=... – FTS + Filter
• POST /api/stories/:slug/entries – Verlauf posten
• GET /api/stories/:slug/entries – Verlauf lesen
• POST /api/nodes/:slug/attachments – Asset anheften

8) Erfolgskriterien (Metriken)

• Time-to-Create: < 2 min vom leeren Story-Draft zum ersten Kapitel
• Konsistenz: < 5% manuelle Korrekturen je 1.000 Wörter (gemessen via Flags/Edits)
• Re-Use: ≥ 30% Stories nutzen bestehende Characters/Places erneut
• Editor-Revert: < 1 min zum Rollback einer Änderung

9) Fahrplan (4–6 Wochen)

1. Woche 1: SvelteKit Grundgerüst, Auth, content_nodes, FTS, RLS.
2. Woche 2: Editor (Markdown), Slug-Parser → _links, List/Detail-Views.
3. Woche 3: story_entries, Timeline-Ansicht, einfache Exporte (Markdown/JSON).
4. Woche 4: Versionierung (node_revisions), Attachments, öffentliche Sharing-Ansicht.
5. Woche 5–6: Feinschliff, Prompt-Guidelines-UX, Konsistenz-Hinweise (leichte Regeln).

---

Kurzfazit: Das text-first + JSONB-Hybrid macht euch maximal schnell, bleibt LLM-ready und hält den DB-Footprint minimal. Mit _links, Revisions und FTS habt ihr genug Struktur für Suche, Wiederverwendung und Konsistenz – ohne die Komplexität klassischer Join-Landschaften.