docs: map existing codebase

2026-04-27 09:13:11 +02:00
parent 15dc0d289a
commit 3e91d5713d
7 changed files with 2237 additions and 0 deletions
--- a/.planning/codebase/INTEGRATIONS.md
+++ b/.planning/codebase/INTEGRATIONS.md
@@ -0,0 +1,226 @@
+# External Integrations
+
+**Analysis Date:** 2026-04-27
+
+## APIs & External Services
+
+**Anthropic Claude API:**
+- Service: Claude API for real-time translation of game content to German
+- What it's used for:
+  - On-demand translation of feats, equipment, spells, items, conditions, and other PF2e content
+  - Translates item effect text for alchemical items
+  - Batches translations in groups for efficiency
+  - Results cached in `Translation` table with quality ratings (HIGH/MEDIUM/LOW)
+  - Fallback: System returns untranslated English names if API key not configured
+  - Model: `claude-haiku-4-5-20251001` (lightweight model for cost-effective translations)
+
+- SDK/Client: `@anthropic-ai/sdk` 0.71.2
+- Auth: Environment variable `ANTHROPIC_API_KEY`
+- Implementation: `server/src/modules/claude/claude.service.ts`
+- Module: `server/src/modules/claude/claude.module.ts`
+- Usage: Called by `server/src/modules/translations/translations.service.ts`
+
+## Data Storage
+
+**Databases:**
+- PostgreSQL 16 (via Docker Compose or production instance)
+  - Connection: Environment variable `DATABASE_URL`
+  - Client: Prisma ORM 7.2.0 with PostgreSQL adapter
+  - Schema: `server/prisma/schema.prisma` (25 models covering users, campaigns, characters, equipment, alchemy, battle, documents)
+  - Migrations: Version-controlled in `server/prisma/migrations/`
+  - Seeding: `server/prisma/seed.ts` (base data), `server/prisma/seed-equipment.ts` (5,482 PF2e items), `server/prisma/seed-feats.ts`
+
+**File Storage:**
+- Local filesystem only (currently)
+  - Directory: Configured via `UPLOAD_DIR` env var (default `./uploads`)
+  - Served via NestJS `ServeStaticModule` at `/uploads` endpoint
+  - Max file size: `MAX_FILE_SIZE` env var (default 10MB)
+  - Types supported: HTML, PDF (from schema `Document` model)
+
+**Caching:**
+- In-memory client state via Zustand (auth store): `client/src/features/auth/hooks/use-auth-store.ts`
+- Server-side caching via TanStack React Query: Automatic cache of API responses with configurable stale times
+- Translation cache in `Translation` table with `@@unique([type, englishName])` constraint
+- No Redis or external cache layer currently
+
+## Authentication & Identity
+
+**Auth Provider:**
+- Custom JWT-based authentication (no external OAuth provider)
+  - Implementation: `server/src/modules/auth/auth.service.ts`
+  - Strategy: Passport.js with JWT strategy (`server/src/modules/auth/strategies/jwt.strategy.ts`)
+  
+**Authentication Flow:**
+1. Users register with username, email, password via `POST /api/auth/register`
+2. Passwords hashed with bcrypt (salt rounds: 10, configurable)
+3. Login returns JWT token valid for `JWT_EXPIRES_IN` (default "7d")
+4. Client stores token in localStorage (persistent) or sessionStorage (session-only)
+   - Determined by "Remember me" checkbox during login
+   - Implementation: `client/src/shared/lib/api.ts`
+5. Token attached to all subsequent requests via Authorization header
+6. Token verified on WebSocket connection via `characters.gateway.ts` and `battle.gateway.ts`
+
+**User Roles:**
+- ADMIN - Full system access
+- GM - Game Master, can manage campaigns, create NPCs, control battles
+- PLAYER - Standard user, can own characters
+
+**Guards:**
+- Global JWT auth guard: `server/src/modules/auth/guards/jwt-auth.guard.ts`
+- Role-based guard: `server/src/modules/auth/guards/roles.guard.ts`
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- None (no Sentry, Rollbar, or external service configured)
+- Server logs to console via NestJS Logger
+- Client console errors only
+
+**Logs:**
+- Server: NestJS Logger (console output in development, can be piped to file in production)
+- Client: Browser console only
+- No centralized logging infrastructure
+
+## CI/CD & Deployment
+
+**Hosting:**
+- Not configured (manual deployment expected)
+- Docker Compose available for local development
+
+**CI Pipeline:**
+- None detected
+- ESLint, Prettier, and tests are run locally before commit
+
+## WebSockets & Real-Time Communication
+
+**Transport:**
+- Socket.io 4.8.3
+- Client library: `socket.io-client` 4.8.3
+- Server: NestJS WebSocket gateways with Socket.io adapter
+
+**Character Updates (Real-Time Sync):**
+- Gateway: `server/src/modules/characters/characters.gateway.ts`
+- Namespace: `/characters`
+- CORS configured from environment variable `CORS_ORIGINS`
+- Authentication: JWT token verified on connection
+- Update types:
+  - `hp` - Health points (current, temp, max)
+  - `conditions` - Add/remove/update character conditions
+  - `item` - Add/remove inventory items
+  - `inventory` - Bulk inventory updates
+  - `money` - Update credits/currency
+  - `level` - Character level changes
+  - `equipment_status` - Mark items as equipped/unequipped/invested
+  - `rest` - Rest cycle triggers (HP restore, condition cleanup)
+  - `alchemy_vials` - Update alchemist versatile vials
+  - `alchemy_formulas` - Add/remove formulae
+  - `alchemy_prepared` - Update prepared alchemical items
+  - `alchemy_state` - Update research field and advanced alchemy state
+  - `dying` - Dying and recovery state
+
+**Battle Updates (Real-Time Sync):**
+- Gateway: `server/src/modules/battle/battle.gateway.ts`
+- Update types:
+  - `token_added` - New combatant token on map
+  - `token_removed` - Token removed
+  - `token_moved` - Position changed
+  - `token_updated` - Stat/property updates
+  - `token_hp_changed` - HP/damage tracking
+  - `initiative_set` - Initiative order
+  - `round_advanced` - Round counter
+  - `session_updated` - Session state
+  - `session_deleted` - Battle session ended
+
+**Client Hooks:**
+- `client/src/features/characters/hooks/use-character-socket.ts` - Character update subscriptions
+- `client/src/features/battle/hooks/use-battle-socket.ts` - Battle update subscriptions
+- Singleton socket pattern to prevent multiple connections
+- Reference counting for cleanup on unmount
+
+## Pathbuilder Integration
+
+**Import Format:**
+- Reads JSON export from Pathbuilder 2e character builder
+- Stored as raw JSON blob in `Character.pathbuilderData` field
+- Used to populate character stats, feats, skills, spells on initial import
+
+**Data Mapping:**
+- Character abilities (STR, DEX, CON, INT, WIS, CHA)
+- Skills with proficiency levels
+- Feats with sources (Class, Ancestry, General, Skill, Bonus, Archetype)
+- Spells with traditions and prepared status
+- Equipment and inventory
+- Alchemy (if applicable)
+
+**Endpoint:**
+- `POST /api/characters/import-pathbuilder` - Import character from Pathbuilder JSON
+
+## Equipment Database
+
+**Data Source:**
+- 5,482 Pathfinder 2e equipment items imported from JSON
+- Seed script: `server/prisma/seed-equipment.ts`
+- Source: JSON data files in `server/prisma/data/`
+
+**Categories:**
+- Weapons (with damage, range, properties)
+- Armor (with AC, penalties, strength requirements)
+- Shields (with HP, hardness, broken threshold)
+- Consumables (potions, scrolls, talismans, etc.)
+- General equipment
+
+**API Endpoints:**
+- `GET /api/equipment` - Search/list equipment
+- `GET /api/equipment/categories` - List available categories
+- `GET /api/equipment/weapons` - Weapon-specific query
+- `GET /api/equipment/armor` - Armor-specific query
+
+## External References
+
+**Archon Omni Documentation (AONPRD):**
+- Links stored in `Feat.url`, `Equipment.url`, `Spell.url`, `Trait.url`
+- Frontend links to official Pathfinder 2e documentation
+- No direct API integration, read-only external links
+
+## Environment Configuration
+
+**Required Environment Variables:**
+
+Server (`server/.env`):
+- `DATABASE_URL` - PostgreSQL connection string (e.g., `postgresql://user:pass@localhost:5432/dimension47?schema=public`)
+- `JWT_SECRET` - Secret key for signing JWT tokens (minimum 32 characters recommended)
+- `JWT_EXPIRES_IN` - Token expiration (default "7d")
+- `PORT` - Server listen port (default 5000)
+- `NODE_ENV` - Environment mode (development/production)
+- `CORS_ORIGINS` - Comma-separated allowed origins (e.g., `http://localhost:5173,http://localhost:3000`)
+- `ANTHROPIC_API_KEY` - Claude API key (optional, disables translations if missing)
+- `UPLOAD_DIR` - File upload directory (default `./uploads`)
+- `MAX_FILE_SIZE` - Max upload size in bytes (default 10485760 = 10MB)
+
+Client (`client/.env`):
+- `VITE_API_URL` - Backend API URL (e.g., `http://localhost:5000/api`)
+
+**Secrets Location:**
+- `.env` files (NOT committed to git, see `.gitignore`)
+- Template files: `server/.env.example` and `client/.env.example`
+- Developers copy examples to `.env` and fill in secrets
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- None configured
+
+**Outgoing:**
+- None configured
+
+## Cross-Domain Communication
+
+**CORS Policy:**
+- Configured via `CORS_ORIGINS` environment variable
+- Applied to HTTP endpoints and WebSocket connections
+- Development allows all `localhost:*` origins
+- Production requires explicit whitelist
+
+---
+
+*Integration audit: 2026-04-27*