# 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
│   │   │       │   ├── alchemy-tab.tsx           # Alchemie-Tab
│   │   │       │   └── rest-modal.tsx            # Rasten-Modal
│   │   │       └── utils/
│   │   │           └── export-character-html.ts  # HTML-Export Funktion
│   │   ├── 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
    │   │   │   └── alchemy.service.ts     # Alchemie-System Service
    │   │   └── 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
  - Alchemie (Phiolen, Formeln, vorbereitete Items)
- **Alchemie-Tab (komplett)**:
  - Vielseitige Phiolen mit Tracker
  - Formelbuch mit allen bekannten Formeln
  - Tägliche Vorbereitung (Advanced Alchemy)
  - Schnelle Alchemie (Quick Alchemy)
  - Handwerkliche Alchemie (Craft Alchemy)
  - Forschungsgebiete (Bomber, Chirurg, Mutageniker, Toxikologe)
  - Infundierte Items mit Effekt-Anzeige und Schadenswerten
- **Rest-System**:
  - HP-Heilung basierend auf CON-Mod × Level
  - Zustands-Management (Erschöpft entfernt, Verdammt/Entkräftet reduziert)
  - Ressourcen-Reset (Zauberplätze, Fokuspunkte)
  - Alchemie-Reset (infundierte Items verfallen, Phiolen aufgefüllt)
- **Status-Tab Erweiterungen**:
  - Wahrnehmung mit korrekter PF2e-Berechnung
  - Geschwindigkeit
  - Rüstungsklasse mit Übungsstufe
  - Rettungswürfe mit Übungsstufen
- **HTML-Export**:
  - Vollständiger Charakterbogen als druckbare HTML-Datei
  - Alle Attribute, Fertigkeiten, Talente, Ausrüstung
  - Zauber und Alchemie (wenn vorhanden)

### Noch zu implementieren (Character Screen)
- **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`)
```bash
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`)
```bash
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

```bash
# 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
```

<!-- GSD:project-start source:PROJECT.md -->
## Project

**Dimension47**

Dimension47 ist eine selbst gehostete Web-App für Pathfinder-2e-Tischrunden auf Deutsch. Sie verwaltet Kampagnen, Charakterbögen mit komplettem PF2e-Regelumfang (HP, Zustände, Inventar, Talente, Aktionen, Alchemie) und stellt einen GM-Battle-Screen mit 3D-Druck-Tisch-Display bereit — alles in Echtzeit synchronisiert. Zielgruppe ist die eigene Spielgruppe, nicht die breite Öffentlichkeit.

**Core Value:** Am Tisch funktioniert alles in Echtzeit und regelkonform: Spieler lesen ihren Charakterbogen am Handy, der GM steuert vom Laptop aus den Battle-Screen, der eingelassene Tisch-Display zeigt die Spielsicht — ohne Reibung, ohne falsche Werte, ohne Reload.

### Constraints

- **Tech-Stack**: NestJS 11 + React 19 + Prisma 7 + PostgreSQL + Socket.io + Tailwind v4 — gesetzt durch Bestand, kein Stack-Wechsel sinnvoll
- **Sprache**: Deutsche UI durchgehend — alle neuen Texte ebenfalls Deutsch
- **Design**: Mobile-First für alle nutzerseitigen Screens (Charakterbogen, Vault-Browser, Würfler, Chat); Battle-GM-Screen darf desktop-fokussiert bleiben; Tisch-Display ist eigener Layout-Modus
- **Daten-Persistenz**: Alle PF2e-Daten gehören in die DB (Prisma-Seeds aus JSON), nichts wird zur Laufzeit aus JSON-Dateien gelesen
- **Migrationen**: Schema-Änderungen ausschließlich über `prisma migrate dev`, niemals `db push`
- **Code-Qualität**: TypeScript strict, keine `any`-Types, kein Quick-Fix der später wehtut
- **Hosting-Modell**: Self-hosted für eigene Spielgruppe — keine Multi-Tenant-/SaaS-Anforderungen
- **Push-Plattform**: Web Push (Service-Worker-basiert), kein FCM/APNs-Native-Wrapper
- **Vault-Endpoint**: Selbst-gehosteter Endpoint (vermutlich auf eigenem Server) — konkretes Protokoll wird in der Vault-Phase entschieden, nicht jetzt
<!-- GSD:project-end -->

<!-- GSD:stack-start source:codebase/STACK.md -->
## Technology Stack

## Languages
- TypeScript 5.9.3 (server), 5.7.3 (client) - Strict mode enabled, full type safety across codebase
- JavaScript (build outputs, scripts)
- HTML/CSS (frontend templates)
## Runtime
- Node.js (version not pinned, assumed LTS) - Used for both server and client dev/build
- ES2023 target (server), ES2022 target (client)
- npm - Lockfiles present for both client and server
## Frameworks
- React 19.2.0 - UI framework
- React Router DOM 7.12.0 - Client-side routing
- Vite 7.2.4 - Build tool and dev server
- NestJS 11.0.1 - Web framework with TypeScript-first design
- Express (via `@nestjs/platform-express`) - Underlying HTTP server
- Tailwind CSS 4.1.18 - Utility-first CSS framework
- `@tailwindcss/vite` plugin for Vite integration
- Jest 30.0.0 - Test runner (server-side only, configured in package.json)
- ts-jest - TypeScript support for Jest
- Supertest 7.0.0 - HTTP assertion library (server integration tests)
- @vitejs/plugin-react - React fast refresh for Vite
## Key Dependencies
- `@prisma/client` 7.2.0 - ORM and database abstraction layer
- `prisma` 7.2.0 - CLI and schema management tool
- `@anthropic-ai/sdk` 0.71.2 - Claude API for on-demand German translations
- `socket.io` 4.8.3 - WebSocket library for real-time communication
- `@nestjs/websockets` 11.1.12 - NestJS WebSocket integration
- `@nestjs/platform-socket.io` 11.1.12 - Socket.io adapter for NestJS
- `@nestjs/jwt` 11.0.2 - JWT authentication provider
- `@nestjs/passport` 11.0.5 - Passport.js integration for authentication
- `passport-jwt` 4.0.1 - JWT strategy for Passport
- `bcrypt` 6.0.0 - Password hashing
- `class-validator` 0.14.3 - Request DTO validation
- `class-transformer` 0.5.1 - DTO transformation
- `@nestjs/swagger` 11.2.5 - OpenAPI/Swagger documentation
- `@nestjs/config` 4.0.2 - Environment configuration management
- `dotenv` 17.2.3 - .env file loading
- `axios` 1.13.2 - HTTP client library for API requests
- `socket.io-client` 4.8.3 - WebSocket client for real-time updates
- `zustand` 5.0.10 - Client state management (auth store)
- `@tanstack/react-query` 5.90.19 - Server state and data fetching (caching, synchronization)
- `react-router-dom` 7.12.0 - Client-side routing
- `framer-motion` 12.26.2 - Animation library
- `lucide-react` 0.562.0 - Icon library (SVG icons)
- `clsx` 2.1.1 - Conditional CSS class utilities
- `tailwind-merge` 3.4.0 - Tailwind class merging utility
- `@nestjs/cli` 11.0.0 - NestJS code generation and project scaffolding
- `@nestjs/schematics` 11.0.0 - Code generators for NestJS
- `prettier` 3.4.2 - Code formatter
- `eslint` 9.18.0 - Linting
- `typescript-eslint` 8.20.0 - TypeScript ESLint support
- `tsx` 4.21.0 - TypeScript execution (used for seed scripts)
- `tsconfig-paths` 4.2.0 - TypeScript path alias resolution
- `ts-node` 10.9.2 - TypeScript REPL and script runner
- `ts-loader` 9.5.2 - TypeScript webpack loader
- `eslint` 9.39.1 - Linting
- `typescript-eslint` 8.46.4 - TypeScript ESLint support
- `eslint-plugin-react-hooks` 7.0.1 - React Hooks linting rules
- `eslint-plugin-react-refresh` 0.4.24 - Vite React refresh linting
## Configuration
- Server loads from `.env` file (see `.env.example`):
- Client loads from `.env` or `.env.local`:
- Server: `server/tsconfig.json` with target ES2023, decorators enabled
- Client: `client/tsconfig.app.json` with target ES2022, strict mode
- Client Vite config: `client/vite.config.ts`
- Server NestJS config: `server/nest-cli.json` (if exists)
## Platform Requirements
- Node.js LTS (tested with v22)
- npm (lockfiles version management)
- PostgreSQL 16+ (via Docker Compose)
- Docker & Docker Compose (for database)
- Git
- Node.js LTS
- PostgreSQL 16+ (managed service or self-hosted)
- Anthropic API key for translations (optional but recommended)
- File storage: Local filesystem or cloud storage (currently local via `./uploads`)
## Database
- Port 5432 (internal), 5433 (exposed for dev)
- Database name: `dimension47`
- Default credentials in docker-compose (dev only)
- pgAdmin 4 included for database management (port 5050)
- Schema: `server/prisma/schema.prisma`
- Generator: Prisma Client with CommonJS module format
- Adapter: `@prisma/adapter-pg` for optimized PostgreSQL queries
- Output: `src/generated/prisma/`
<!-- GSD:stack-end -->

<!-- GSD:conventions-start source:CONVENTIONS.md -->
## Conventions

## Naming Patterns
- Components: kebab-case (e.g., `character-sheet-page.tsx`, `add-condition-modal.tsx`, `hp-control.tsx`)
- Utilities/Services: kebab-case (e.g., `use-character-socket.ts`, `export-character-html.ts`)
- Directories: kebab-case (e.g., `features/`, `shared/`, `components/`)
- camelCase for all function names
- Hooks prefixed with `use` (e.g., `useAuthStore`, `useCharacterSocket`, `useMemo`, `useState`)
- Event handlers prefixed with `handle` (e.g., `handleApply`, `handleConnection`, `handleDisconnect`)
- Getter/setter methods follow camelCase (e.g., `getToken()`, `setToken()`)
- camelCase for all variable names
- Constants in UPPER_SNAKE_CASE (e.g., `PROFICIENCY_BONUS`, `SKILL_DATA`, `TABS`)
- Type unions with capitalized names (e.g., `CharacterType`, `AbilityType`, `TabType`)
- Boolean prefixes: `is`, `has`, `should`, `can` (e.g., `isLoading`, `isOwner`, `hasAccess`)
- PascalCase for all types, interfaces, and enums
- Domain types in shared: `Character`, `Campaign`, `User`, `CharacterItem`, `CharacterFeat`
- Props interfaces suffixed with `Props` (e.g., `HpControlProps`, `AddConditionModalProps`)
- DTO interfaces suffixed with `Dto` (e.g., `CreateCharacterDto`, `LoginDto`, `RegisterDto`)
- State types in Zustand: domain-specific (e.g., `AuthState`)
## Code Style
- Prettier configured in `server/.prettierrc` with:
- Line length: implicit (Prettier default ~80 chars but allows overflow)
- Indentation: 2 spaces
- Client: ESLint 9 with flat config (`eslint.config.js`)
- Server: ESLint 9 with flat config (`eslint.config.mjs`)
- **Strict Mode Enforced** on client (`client/tsconfig.app.json`):
- Server TypeScript (`server/tsconfig.json`):
## Import Organization
- Client: `@/*` → `./src/*` (defined in `vite.config.ts` and `tsconfig.app.json`)
- Server: No path alias configured; uses relative paths
- Always use `@/` prefix on client to avoid relative path hell
- Barrel files used: `features/*/index.ts`, `shared/components/ui/index.ts`
- Default exports on pages: `export default App`
- Named exports for utilities, types, hooks: `export { HpControl }`, `export const api = new ApiClient()`
## Error Handling
- Use NestJS exception classes: `NotFoundException`, `ForbiddenException`, `UnauthorizedException`, `ConflictException`
- Access checks before operations (e.g., `checkCampaignAccess()`, `checkCharacterAccess()` in `characters.service.ts`)
- Return meaningful error messages: "Campaign not found", "No access to this campaign"
- Prisma operations wrapped in try-catch only when necessary for data validation
- JWT verification throws exceptions through guard: `JwtAuthGuard` handles 401s
- Axios interceptors for request/response handling (in `api.ts`)
- 401 errors trigger logout and redirect to `/login` (except auth endpoints)
- Error state in components: `isLoading`, `error`, `pendingChange` states
- Modal operations: try/catch with `setIsLoading(false)` in finally block
- Error logging: `console.error()` for debugging, no silent failures
- User feedback: Navigation on error (`navigate()`) or via error state
- Token validation on connection (throws `client.disconnect()`)
- Logger for all connection/disconnection events
- Errors logged but don't crash server
## Logging
- Server: NestJS `Logger` (in modules/gateways)
- Client: `console.error()` for error debugging
- Server logs connection events with user context
- Client silently catches most errors, logs critical ones
- No debug logging infrastructure in place
## Comments
- Constants with unclear meaning (e.g., `PROFICIENCY_BONUS` values, skill-to-ability mappings)
- Complex calculations (e.g., HP percentage calculations)
- Business logic that isn't immediately obvious (e.g., Pathfinder 2e rules)
- NOT used for obvious code ("increment counter")
- Minimal usage observed
- API methods documented with Swagger decorators on server: `@ApiOperation()`, `@ApiResponse()`
- No runtime JSDoc comments in source
## Function Design
- Modal components: 500-1700 lines (large, but feature-complete)
- Service methods: 10-50 lines (concise, focused)
- Utility functions: 5-20 lines
- Interface-based: Pass objects instead of multiple params
- Optional params with defaults: `remember: boolean = false`
- Async functions return typed Promises: `async getCharacter(): Promise<Character>`
- Component callbacks: callbacks are async promises (`onHpChange: (newHp: number) => Promise<void>`)
- Services return full domain objects with relations included
## Module Design
- Components export as named: `export function HpControl() { ... }`
- Utilities export as named: `export const api = new ApiClient()`
- One export per file (generally)
- Used in features: `features/auth/index.ts` re-exports `useAuthStore`, `LoginPage`, `RegisterPage`
- Used for UI components: `shared/components/ui/index.ts` re-exports all buttons, cards, inputs
- Reduces import complexity
- NestJS @Injectable() decorator for services
- Constructor injection: `constructor(private prisma: PrismaService)`
- Circular dependencies resolved with @Inject(forwardRef()): seen in `CharactersService`
## State Management
- Single store pattern: `create<AuthState>()`
- Persisted state with middleware: `persist()`
- Partialize: stores only non-sensitive fields (`user`, `isAuthenticated`)
- Actions as methods in store: `login()`, `logout()`, `checkAuth()`
- Error state in store: `error: string | null`
- No client state management needed
- WebSocket gateway maintains connection map: `connectedClients = new Map()`
## Design Tokens (UI)
- Primary: Magenta `#c26dbc` (in Tailwind as `primary-500`, `primary-600`, etc.)
- Secondary: Dark grays for dark mode (`secondary-800`, `secondary-700`)
- Text: Primary (light), secondary (dimmer), tertiary (dimmest)
- Background: Primary, secondary, tertiary layers
- Error: Red (`error-500`, `error-600`)
- Success: Green (`green-500`)
- Warning: Yellow (`yellow-500`)
- Font sizes: sm, base, lg (Tailwind defaults)
- Weights: normal, medium (600), semibold
- All UI text in German except code/technical terms
- Lucide React exclusively (e.g., `Heart`, `Swords`, `BookOpen`, `Package`)
- No emoji anywhere
- Icon sizes: `h-4 w-4` (standard), `h-6 w-6` (large)
- Minimum 44px (mobile-first, accessible)
- Buttons: `h-11` (44px), `h-9` (36px for small), `h-12` (48px for large)
- Icon buttons: `h-11 w-11` (44x44px)
- Tailwind v4 defaults: `p-4`, `gap-2`, `rounded-lg`, `rounded-2xl`
- Modals: `rounded-t-2xl sm:rounded-2xl` (bottom sheet on mobile, centered on desktop)
- Mobile-first breakpoints: `sm:` prefix for tablet+ (e.g., `sm:items-center`, `sm:rounded-2xl`)
- Flexbox for layouts: `flex`, `flex-col`, `items-center`, `justify-between`
- Grid rarely used
<!-- GSD:conventions-end -->

<!-- GSD:architecture-start source:ARCHITECTURE.md -->
## Architecture

## Pattern Overview
- Modular NestJS architecture with feature-based modules (Auth, Characters, Campaigns, Equipment, Battle)
- Feature-first React organization with shared components and hooks
- WebSocket Gateway real-time sync for character and battle state
- Role-based access control (ADMIN, GM, PLAYER) enforced globally
- Prisma ORM for PostgreSQL data persistence
- JWT-based stateless authentication
## Layers
- Purpose: HTTP request handling and routing
- Location: `server/src/modules/*/[feature].controller.ts`
- Contains: REST endpoints with decorators (@Post, @Get, @Put, @Patch, @Delete)
- Depends on: Services, DTOs, Guards, Decorators
- Used by: HTTP clients (React frontend)
- Examples:
- Purpose: Business logic, data processing, validation
- Location: `server/src/modules/*/[feature].service.ts`
- Contains: Methods for creating, updating, deleting entities; complex calculations
- Depends on: PrismaService, other Services, external APIs (Claude)
- Used by: Controllers, Gateways, other Services
- Examples:
- Purpose: Real-time bidirectional communication for live updates
- Location: `server/src/modules/*/[feature].gateway.ts`
- Contains: Socket.io event handlers, authentication, room management
- Depends on: JwtService, PrismaService, Services
- Used by: React WebSocket hooks
- Examples:
- Purpose: Database abstraction and ORM
- Location: `server/src/prisma/prisma.service.ts`
- Contains: Prisma client wrapper, query interface
- Depends on: PostgreSQL database
- Used by: All Services
- Data Models defined in: `server/prisma/schema.prisma`
- Purpose: Isolated feature domains with components, hooks, types
- Location: `client/src/features/[feature]/`
- Contains: Components, hooks, index.ts barrel exports
- Examples:
- Purpose: Reusable components, hooks, utilities, types across features
- Location: `client/src/shared/`
- Contains:
- Used by: All features
- Purpose: Navigation and route protection
- Location: `client/src/App.tsx`
- Contains: React Router v6 routes, protected route wrapper
- Depends on: React Router, Feature components
- Entry point: `client/src/main.tsx`
- Purpose: Client-side state persistence
- Location: `client/src/features/auth/hooks/use-auth-store.ts`
- Contains: Zustand store for authentication state
- Used by: Auth-related components, ProtectedRoute
## Data Flow
### Character Update (Real-Time WebSocket Sync)
### Equipment Database Search
### Character Creation (Pathbuilder Import)
### Battle Session Synchronization
### Alchemy System State
## Key Abstractions
- Purpose: Database abstraction, query builder
- Location: `server/src/prisma/prisma.service.ts`
- Pattern: Singleton service injected into all modules
- Used for: All CRUD operations, complex queries with relations
- Purpose: Authentication and authorization
- Location: 
- Pattern: NestJS guards executed globally on every request
- Metadata: `@Roles()` and `@Public()` decorators control per-endpoint behavior
- Purpose: HTTP communication abstraction
- Location: `client/src/shared/lib/api.ts`
- Pattern: Singleton class with axios instance
- Features: Token management, auto-retry, auth interceptors, 401 handling
- Purpose: Prevent duplicate connections, manage subscriptions
- Location: `client/src/shared/hooks/use-character-socket.ts`
- Pattern: Global socket singleton with ref counting
- Features: Auto-reconnect, polling fallback, room subscription
- Purpose: Type-safe event dispatch
- Location: 
- Pattern: Union types for event kind discrimination
## Entry Points
- Location: `server/src/main.ts`
- Triggers: `npm run start:dev` or deployed container startup
- Responsibilities:
- Location: `client/src/main.tsx`
- Triggers: Browser page load or `npm run dev`
- Responsibilities:
- Location: `client/src/App.tsx`
- Pattern: React Router v6 with protected routes
- Flow:
## Error Handling
- `NotFoundException` - 404 when entity not found
- `ForbiddenException` - 403 when user lacks permission
- `BadRequestException` - 400 for invalid input
- `UnauthorizedException` - 401 for auth failures
- Global error filter could be added for consistent formatting
- Service methods validate access before querying: `checkCampaignAccess()`, `checkCharacterAccess()`
- API client `response.interceptors` catches 401 → redirects to /login
- Components wrapped in error boundaries (future enhancement)
- Failed requests return rejected promises to component
- Token verification on connection → disconnect if invalid
- No structured error responses; silent failures with console logging
- Clients auto-reconnect via socket.io configuration
## Cross-Cutting Concerns
- Backend: NestJS Logger class used in services/gateways
- Frontend: Console.log for development (socket.io events log connection state)
- Backend: Global ValidationPipe with DTOs (class-validator)
- Frontend: Form validation in components (manual checks in modals)
- Prisma schema enforces constraints (NOT NULL, unique, enums)
- Backend: JwtAuthGuard applied globally in app.module.ts
- Endpoints opt-out via @Public() decorator
- WebSocket: Token verified in gateway.handleConnection()
- Frontend: Token stored in localStorage (persistent) or sessionStorage (session-only)
- Backend: RolesGuard checks @Roles() metadata
- Service methods verify campaign/character ownership before allowing operations
- Pattern: Check campaign membership → check character ownership → allow operation
- WebSocket Gateway manages rooms (one room per character/session)
- Clients join room on component mount, leave on unmount
- Broadcasts to all clients in room except sender (optional)
<!-- GSD:architecture-end -->

<!-- GSD:skills-start source:skills/ -->
## Project Skills

No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file.
<!-- GSD:skills-end -->

<!-- GSD:workflow-start source:GSD defaults -->
## GSD Workflow Enforcement

Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.

Use these entry points:
- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks
- `/gsd-debug` for investigation and bug fixing
- `/gsd-execute-phase` for planned phase work

Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
<!-- GSD:workflow-end -->

<!-- GSD:profile-start -->
## Developer Profile

> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile.
> This section is managed by `generate-claude-profile` -- do not edit manually.
<!-- GSD:profile-end -->
