227 lines
8.6 KiB
Markdown
227 lines
8.6 KiB
Markdown
# 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*
|