whalehunting/.planning/codebase/INTEGRATIONS.md

# External Integrations

**Analysis Date:** 2026-02-04

## APIs & External Services

**Not applicable** - No external APIs integrated. Game is fully self-contained.

## Data Storage

**Databases:**
- Not applicable - No database required or used
- Game state is managed in-memory during gameplay
- State location: Passed via scene parameters in `src/main.js`

**File Storage:**
- Local filesystem only - Assets would be bundled with application
- No remote file storage configured
- Asset directories (planned): `assets/sprites/`, `assets/backgrounds/`

**Caching:**
- Browser caching only - Static assets cached by nginx (1 year TTL)
- No server-side caching layer
- Vite dev server handles hot module replacement during development

**State Management:**
- Phaser Scene-based state management
- Game state example from `src/scenes/IntroScene.js`:
  ```javascript
  const inventory = {
      whaleOil: 0,
      fuel: 100,
      penguins: 0
  };
  this.scene.start('ShipDeckScene', { inventory: inventory });
  ```
- State passed between scenes as parameters
- No persistence layer (state resets on page refresh)

## Authentication & Identity

**Not applicable** - No user authentication
- Game is anonymous and stateless
- No user accounts or login required
- All players access the same game instance

## Monitoring & Observability

**Error Tracking:**
- Not integrated
- Console errors only (browser developer tools)
- No remote error reporting configured

**Logs:**
- Browser console logging only
- Nginx access logs available in container at `/var/log/nginx/`
- Docker container logs accessible via: `docker-compose logs -f`
- Vite dev server logs to terminal

**Health Checks:**
- Docker health check: `wget --quiet --tries=1 --spider http://127.0.0.1/`
- Interval: 30 seconds
- Timeout: 3 seconds
- Retries: 3 before marking unhealthy
- Start period: 5 seconds

## CI/CD & Deployment

**Hosting:**
- Docker container on `node03.tricnet.de`
- Served via Nginx (Alpine Linux)
- Manual deployment via `deploy.sh`

**CI Pipeline:**
- Not detected - No automated CI/CD system configured
- Deployment process: Manual `./deploy.sh`
  - Uses rsync to sync files to node03
  - SSH to rebuild Docker container
  - Rebuilds docker-compose services

**Deployment Method:**
- Deployment file: `deploy.sh`
- Sync target: `tho@node03.tricnet.de:/home/tho/whalehunting/`
- Excludes: `node_modules/`, `dist/`, `.git/`, `.DS_Store`
- Build command: `docker-compose down && docker-compose up -d --build`

## Environment Configuration

**Required env vars:**
- None - Game requires no environment variables at runtime
- Docker container runs with default environment

**Secrets location:**
- Not applicable - No secrets, API keys, or credentials required
- SSH key required for deployment (stored on developer machine)

**Development Environment:**
- Game automatically runs on `http://localhost:5173` (Vite default)
- Playwright configured to use `http://localhost:5173` as baseURL
- No .env file needed for development

## Webhooks & Callbacks

**Incoming:**
- Not applicable - No webhooks received

**Outgoing:**
- Not applicable - No webhooks sent
- Game makes no HTTP requests

## Network Requirements

**Development:**
- Must be able to access `localhost:5173` (Vite dev server)
- Must be able to access `localhost:5173` for Playwright E2E tests
- Vitest UI server binds to `0.0.0.0:51204` (all interfaces)

**Production:**
- Must be accessible on port 8880 (external Docker port)
- Health checks require outbound HTTP to `http://127.0.0.1/` (internal to container)
- No outbound internet access required from game runtime

## Data Flow

**Client-Side Only:**
- All game logic runs in browser
- No data sent to any backend or external service
- Game state never persists (no save/load feature implemented)
- Player actions: Click/tap interactions → Phaser input handlers → Scene state changes

**Example State Flow** (from `src/scenes/IntroScene.js`):
1. User clicks "SET SAIL" button
2. Button click handler creates inventory object
3. Scene transitions: `this.scene.start('ShipDeckScene', { inventory })`
4. ShipDeckScene receives inventory via init parameter
5. Game continues with same inventory state

## Testing Infrastructure

**Unit Tests:**
- Framework: Vitest 4.0.16
- Environment: jsdom
- Test directory: `tests/unit/`
- Run: `npm run test` or `npm run test:ui` (with visual UI)
- Coverage: `npm run test:coverage`

**E2E Tests:**
- Framework: Playwright 1.57.0
- Test directory: `tests/e2e/`
- Browsers tested: Chromium, iPhone 12 (mobile)
- Run: `npm run test:e2e` or `npm run test:e2e:ui`
- Screenshots: Captured on failure only
- Traces: Captured on first retry

**Test Configuration Files:**
- `vitest.config.js` - Unit test setup
- `playwright.config.js` - E2E test setup

---

*Integration audit: 2026-02-04*