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:

  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