Dimension-47/CLAUDE.md

Dimension47 - TTRPG Campaign Management Platform

Projekt-Philosophie

Qualität vor Geschwindigkeit: Es ist egal, wie lange die Implementierung dauert - das System soll am Ende gut funktionieren. Keine Shortcuts oder Quick-Fixes, die später Probleme verursachen.

Lieber langsam und richtig: Immer den sauberen Weg wählen, auch wenn er länger dauert. Beispiele:

• Prisma Migrations statt db push verwenden
• Daten in Datenbank statt direkt aus JSON-Dateien lesen
• Proper Error Handling statt try/catch mit console.log
• TypeScript strict mode, keine any Types

Architektur-Entscheidungen

Daten-Management

• Equipment/Items in Datenbank: Alle Pathfinder 2e Daten (Waffen, Rüstungen, Ausrüstung, Zauber, Talente) werden in die PostgreSQL-Datenbank importiert, NICHT direkt aus JSON-Dateien gelesen.
• Prisma Seed Scripts: JSON-Dateien werden via prisma db seed in die Datenbank importiert.
• Übersetzungen gecacht: Deutsche Übersetzungen werden on-demand via Claude API generiert und in der Translation-Tabelle gespeichert.

Vorteile des Database-Ansatzes

• Bessere Such- und Filtermöglichkeiten
• Konsistente Datenstruktur
• Eigene Items können hinzugefügt werden
• Relationale Verknüpfungen möglich
• Performance durch Indizes

Tech Stack

Frontend

• React 19 + TypeScript
• Vite als Build Tool
• Tailwind CSS v4
• shadcn/ui Komponenten (selbst gebaut)
• Zustand für Client State

Backend

• NestJS mit TypeScript
• Prisma ORM
• PostgreSQL
• JWT Authentication
• Socket.io für WebSockets

Ordnerstruktur

dimension47/
├── client/                 # React Frontend
│   ├── src/
│   │   ├── app/           # App-Config, Router
│   │   ├── features/      # Feature-Module (auth, campaigns, characters, etc.)
│   │   │   ├── auth/components/
│   │   │   │   ├── login-page.tsx            # Login mit Animationen
│   │   │   │   └── register-page.tsx         # Registrierung
│   │   │   └── characters/components/
│   │   │       ├── character-sheet-page.tsx  # Hauptseite mit Tabs
│   │   │       ├── hp-control.tsx            # HP-Management Komponente
│   │   │       ├── add-condition-modal.tsx   # Zustand hinzufügen
│   │   │       ├── add-item-modal.tsx        # Item aus DB hinzufügen
│   │   │       └── actions-tab.tsx           # Aktionen-Tab
│   │   ├── shared/        # Geteilte Komponenten, Hooks, Types
│   │   │   └── hooks/
│   │   │       └── use-character-socket.ts   # WebSocket Hook für Echtzeit-Sync
│   │   └── assets/
│   └── public/            # Statische Dateien, JSON-Datenbanken
│
└── server/                 # NestJS Backend
    ├── src/
    │   ├── modules/       # Feature-Module
    │   │   ├── auth/      # Authentifizierung
    │   │   ├── campaigns/ # Kampagnenverwaltung
    │   │   ├── characters/# Charakterverwaltung
    │   │   │   └── characters.gateway.ts  # WebSocket Gateway
    │   │   └── equipment/ # Equipment-Datenbank
    │   ├── common/        # Shared Utilities
    │   └── prisma/        # Prisma Service
    └── prisma/
        ├── schema.prisma  # Datenbank-Schema
        ├── migrations/    # Prisma Migrations
        ├── seed.ts        # Basis-Seed
        ├── seed-equipment.ts # Equipment-Import (5.482 Items)
        └── data/          # JSON-Quelldaten für Equipment

Implementierte Features

Auth

• JWT-basierte Authentifizierung
• Login/Register/Logout
• Rollen: ADMIN, GM, PLAYER
• "Anmeldung speichern" Funktion (localStorage vs sessionStorage)
• Animierter Login-Screen:
  • Zweistufiger Flow: Splash → Formular
  • Animierter Sternenhintergrund mit schwebenden Orbs
  • "DIMENSION 47" Titel mit Buchstaben-Animation und Glow-Effekt
  • Logo mit Tap-Glow-Effekt
  • Gestaffelte Formular-Animationen (Komponente für Komponente)

Kampagnen

• CRUD für Kampagnen
• Mitgliederverwaltung
• GM-Berechtigungen

Charaktere

• Pathbuilder 2e Import
• HP-Management (mobile-optimiert, Schaden/Heilung/Direkt)
• Zustände (Conditions) mit PF2e-Datenbank
• Fertigkeiten mit deutschen Namen
• Rettungswürfe
• Inventar-System (komplett):
  • Vollständige Equipment-Datenbank (5.482 Items)
  • Item-Suche mit Kategoriefilter und Pagination
  • Bulk-Tracking mit Belastungs-Anzeige
  • Ausrüstungsstatus (angelegt/abgelegt/investiert)
  • Quantity-Management
  • Item-Details mit Eigenschaften, Schaden, etc.
  • Benutzerdefinierte Notizen pro Item
• Talente-Tab (komplett):
  • Alle Charaktertalente aus Pathbuilder-Import
  • Kategorisiert nach Quelle (Klasse, Abstammung, Allgemein, Fertigkeit, Bonus, Archetyp)
  • Einklappbare Kategorien
  • Talentdetails mit Beschreibung und Voraussetzungen
• Aktionen-Tab mit PF2e-Aktionsdatenbank (99 Aktionen)
  • Kategorien: Allgemein, Kampf, Bewegung, Interaktion, Spezial
  • Einklappbare Kategorien (standardmäßig eingeklappt)
  • Aktionstyp-Icons (Aktion, Reaktion, Freie Aktion, etc.)
  • Suchfunktion
• WebSocket Real-Time Sync für:
  • HP (aktuell, temporär, max)
  • Zustände (hinzufügen, entfernen, aktualisieren)
  • Inventar (Items hinzufügen, entfernen, aktualisieren)
  • Ausrüstungsstatus (angelegt/abgelegt)
  • Geld (Credits)
  • Level

Noch zu implementieren (Character Screen)

• Alchemie-Tab: Alchemistische Formeln und Rezepte
• Level-Up System: Stufenaufstieg mit Attributs-, Talent- und Fertigkeitenwahl

Equipment-Datenbank

• 5.482 Items aus Pathfinder 2e importiert
• Waffen mit Schaden, Schadentyp, Reichweite, Eigenschaften
• Rüstungen mit RK, DEX-Cap, Penalties
• Verbrauchsgüter und allgemeine Ausrüstung
• Durchsuchbar nach Name, Kategorie, Level, Eigenschaften
• API-Endpunkte: /equipment, /equipment/categories, /equipment/weapons, etc.

Design-Prinzipien

• Mobile-First: Touch-optimiert mit 44px+ Touch-Targets
• Dark Mode: Primärfarbe #c26dbc (Magenta)
• Deutsch: Alle UI-Texte auf Deutsch
• Keine Emojis: Nur Lucide Icons

Environment-Variablen

Server (server/.env)

PORT=5000                    # Server-Port
DATABASE_URL="postgresql://..." # PostgreSQL Connection String
JWT_SECRET="..."             # JWT Signing Key
ANTHROPIC_API_KEY="..."      # Claude API für Übersetzungen

Client (client/.env)

VITE_API_URL=http://localhost:5000/api  # Muss mit Server PORT übereinstimmen

Wichtig: Die WebSocket-URL wird automatisch aus VITE_API_URL abgeleitet (ohne /api Suffix).

Beispiel-Dateien: server/.env.example und client/.env.example

Entwicklung

# Backend starten (Port 5000, konfigurierbar via PORT in .env)
cd server && npm run start:dev

# Frontend starten (Port 5173)
cd client && npm run dev

# Prisma Migrations (IMMER Migrations verwenden, NIEMALS db push!)
cd server && npm run db:migrate:dev      # Neue Migration erstellen & anwenden
cd server && npm run db:migrate:deploy   # Migrations in Produktion anwenden
cd server && npm run db:migrate:status   # Status der Migrations prüfen
cd server && npm run db:migrate:reset    # DB zurücksetzen (Dev only!)

# Prisma Sonstiges
cd server && npm run db:studio           # DB Browser
cd server && npm run db:generate         # Prisma Client generieren
cd server && npm run db:seed             # Basis-Seed-Daten laden
cd server && npm run db:seed:equipment   # Equipment-Datenbank laden