whalehunting/.planning/codebase/STACK.md

Technology Stack

Analysis Date: 2026-02-04

Languages

Primary:

• JavaScript (ES6 modules) - All source code and configuration

Runtime

Environment:

• Node.js 20 (Alpine) - Development and build time
• Browser (Chromium, Safari) - Runtime environment for game

Package Manager:

• npm - Dependency management
• Lockfile: package-lock.json (present)

Frameworks

Core:

• Phaser 3.80.1 - 2D game framework and physics engine
  • Used in: src/main.js and all scene files
  • Provides game loop, rendering, input handling, physics (arcade)

Build/Dev:

• Vite 5.0.0 - Build tool and development server
  • Config: Not detected (uses Vite defaults)
  • Dev server: Port 5173 (standard)
  • Output directory: dist/

Testing:

• Vitest 4.0.16 - Unit test framework

  • Config: vitest.config.js
  • Environment: jsdom (browser-like environment for testing)
  • UI: @vitest/ui 4.0.16 for visual test runner

• Playwright 1.57.0 - E2E testing framework

  • Config: playwright.config.js
  • Test directory: tests/e2e/
  • Browsers: Chromium, iPhone 12 (mobile simulation)
  • Screenshots: Captured on test failure

Key Dependencies

Critical:

• phaser (3.80.1) - Complete game development framework
  • Why it matters: Core engine for all game logic, rendering, and physics

Development Only:

• @playwright/test (1.57.0) - E2E test runner with browser automation
• @vitest/ui (4.0.16) - Visual UI for viewing test results
• jsdom (27.3.0) - DOM implementation for testing in Node.js environment
• vite (5.0.0) - Lightning-fast build tool and dev server
• vitest (4.0.16) - Unit test framework built on Vite

Configuration

Environment:

• No environment variables required for runtime
• Game runs entirely in browser with no backend dependencies

Build:

• vite.config.js - Not present (uses defaults)
• playwright.config.js - E2E test configuration
• vitest.config.js - Unit test configuration with jsdom environment
• Vite configured for module type: module (ES6)

Platform Requirements

Development:

• Node.js 20+
• npm 8+ (included with Node 20)
• Git (for version control)
• Linux/macOS/Windows (any platform with Node.js)

Production:

• Nginx web server (Alpine Linux image)
• Docker (for containerized deployment)
• Static file hosting (game is fully client-side)
• No database required
• No backend API required

Build & Deployment

Development:

npm install          # Install dependencies
npm run dev          # Start dev server on port 5173
npm run test         # Run unit tests
npm run test:ui      # Run tests with visual UI
npm run test:e2e     # Run Playwright E2E tests

Production:

npm run build        # Build to dist/ directory
docker build -t whalehunting-game .  # Build Docker image
docker-compose up -d # Deploy with Docker Compose

Docker Stack:

• Base image: nginx:alpine (production serving)
• Build stage: node:20-alpine (build application)
• Port: 8880 (external), 80 (container)
• Health checks: wget ping every 30s
• Network: Docker bridge network whalehunting-network

Deployment Target:

• Docker container on node03.tricnet.de
• Deployed via rsync + SSH (see deploy.sh)
• Game served at: http://node03.tricnet.de:8880

Performance Optimizations

Build:

• Vite provides fast module bundling
• Production build is minified and optimized

Runtime:

• Phaser uses WebGL/Canvas rendering (automatic selection via Phaser.AUTO)
• Game configured with fixed dimensions (800x600) with responsive scaling
• Responsive scaling mode: FIT with auto-centering
• Min viewport: 320x240 (mobile support)
• Arcade physics engine configured with no gravity (2D top-down view)

Serving:

• Nginx configured with gzip compression
• Static asset caching: 1 year (as noted in README)
• Health checks ensure container availability

---

Stack analysis: 2026-02-04