Dimension-47/.planning/codebase/INTEGRATIONS.md

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