whalehunting/.planning/codebase/STRUCTURE.md

# Codebase Structure

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

## Directory Layout

```
whalehunting/
├── src/                    # Game source code
│   ├── main.js            # Phaser game initialization and configuration
│   └── scenes/            # Game scene implementations
│       ├── IntroScene.js
│       ├── ShipDeckScene.js
│       ├── MapScene.js
│       ├── TransitionScene.js
│       └── HuntingScene.js
├── tests/                 # Test suites
│   ├── unit/              # Unit tests (Vitest)
│   │   └── game-logic.test.js
│   └── e2e/               # End-to-end tests (Playwright)
│       └── game-flow.spec.js
├── .planning/             # GSD planning documents
│   └── codebase/          # Architecture analysis
├── index.html             # HTML entry point
├── package.json           # Dependencies and scripts
├── vitest.config.js       # Unit test configuration
├── playwright.config.js   # E2E test configuration
├── nginx.conf             # Web server config for deployment
├── Dockerfile             # Container image definition
├── docker-compose.yml     # Multi-container orchestration
└── deploy.sh              # Automated deployment script
```

## Directory Purposes

**src/:**
- Purpose: All game source code
- Contains: Main game initialization and scene implementations
- Key files: `main.js` is the entry point that configures Phaser

**src/scenes/:**
- Purpose: Game scene implementations
- Contains: Five scene classes, one per major game location/mode
- Key files: IntroScene starts the game, HuntingScene has most complex logic

**tests/:**
- Purpose: All test code separated from source
- Contains: Unit tests and E2E tests in separate subdirectories
- Key files: `game-logic.test.js` for game mechanics, `game-flow.spec.js` for user flows

**tests/unit/:**
- Purpose: Logic testing without Phaser
- Contains: Vitest tests for inventory calculations, fuel costs, barrel logic
- Key files: `game-logic.test.js`

**tests/e2e/:**
- Purpose: Full application flow testing
- Contains: Playwright tests simulating user interactions on actual game canvas
- Key files: `game-flow.spec.js`

**.planning/codebase/:**
- Purpose: Analysis documents for code navigation
- Contains: ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md
- Generated by: GSD mapping processes

## Key File Locations

**Entry Points:**
- `index.html`: Browser loads this, contains game-container div and script import
- `src/main.js`: Phaser game configuration and scene list initialization

**Configuration:**
- `vitest.config.js`: Unit test runner with jsdom environment, port 51204 for UI server
- `playwright.config.js`: E2E test runner with Chromium and iPhone 12 profiles
- `package.json`: Dependencies (Phaser 3.80.1, Vite, Vitest, Playwright)
- `nginx.conf`: Web server routing (not actively used in dev)
- `docker-compose.yml`: Local dev: port 5173 for Vite server
- `Dockerfile`: Production build with multi-stage for size optimization

**Core Logic:**
- `src/scenes/IntroScene.js`: Game entry, starts with fuel=100, oil=0, penguins=0
- `src/scenes/ShipDeckScene.js`: Inventory display, barrel visualization, penguin cage reveal
- `src/scenes/MapScene.js`: Location selection (Hunting Grounds, Antarctic, Port)
- `src/scenes/TransitionScene.js`: Atmospheric journey scenes, destination-specific visuals
- `src/scenes/HuntingScene.js`: Core gameplay - whale spawning, harpoon mechanics, fuel consumption

**Testing:**
- `tests/unit/game-logic.test.js`: Barrel calculations, inventory limits, fuel costs, whale health, crosshair clamping
- `tests/e2e/game-flow.spec.js`: Full flows (intro→ship→map→hunting), mobile viewport, desktop scaling

## Naming Conventions

**Files:**
- PascalCase + Scene suffix: `IntroScene.js`, `ShipDeckScene.js`
- camelCase for non-scene modules: Would apply if utilities existed
- Test files: Matched source with `.test.js` or `.spec.js` suffix
- Config files: kebab-case: `playwright.config.js`, `vitest.config.js`

**Directories:**
- lowercase plural: `src/scenes/`, `tests/unit/`, `tests/e2e/`
- camelCase for compound: Not currently used

**Class Names:**
- PascalCase: `IntroScene`, `ShipDeckScene`, `MapScene`, `TransitionScene`, `HuntingScene`
- Extend `Phaser.Scene` directly

**Methods:**
- camelCase: `create()`, `update()`, `init()`, `createDeck()`, `createBarrels()`, `updateInventoryDisplay()`
- Lifecycle methods (create, update) are Phaser conventions
- Helper methods prefix with action: `create*()`, `update*()`, `show*()`, `draw*()`

**Variables:**
- camelCase for instance: `this.inventory`, `this.currentWhale`, `this.harpoons`
- camelCase for local: `barrelCount`, `swimSpeedX`, `healthPercent`
- UPPERCASE for constants: `FUEL_COST = 2`, `MAX_HEALTH = 3`

**Game State Objects:**
- Inventory structure: `{ whaleOil: number, fuel: number, penguins: number }`
- Whale data stored via `setData()`: `health`, `alive`, `diving`, `swimSpeedX`, `swimSpeedY`, `direction`

## Where to Add New Code

**New Scene/Location:**
1. Create `src/scenes/NewScene.js` extending Phaser.Scene
2. Implement `init(data)` to receive inventory
3. Implement `create()` for rendering
4. Implement `update()` if frame-by-frame logic needed
5. Call `this.scene.start('MapScene', { inventory: this.inventory })` to transition
6. Add to scene list in `src/main.js` config array
7. Add location marker in `MapScene.js` that routes to new scene

**New Game Mechanic:**
- Hunting scene has most game logic: HuntingScene.js handles whale spawning, harpoon firing, collision detection, health tracking
- Add mechanics as methods in relevant scene class
- Store persistent state in `this.inventory` object
- Display UI changes via `updateInventoryDisplay()` pattern

**Utilities (if needed):**
- Create `src/utils/` directory for shared helpers
- Example: `src/utils/inventory.js` for max capacity functions
- Example: `src/utils/collision.js` for distance calculations
- Import in scenes: `import { calculateBarrels } from '../utils/inventory.js';`

**New UI Component Pattern:**
- Create methods in scene: `createInventoryDisplay()`, `createMessageBox()`
- Return reference to element for later updates
- Update via methods: `updateInventoryDisplay()`, `showMessage(text)`
- Use semi-transparent rectangles for panels with `.setFillStyle(0x000000, 0.7)`

## Special Directories

**node_modules/:**
- Purpose: Installed dependencies
- Generated: Yes (via npm install)
- Committed: No (.gitignore)

**dist/:**
- Purpose: Vite production build output
- Generated: Yes (via npm run build)
- Committed: No (.gitignore)
- Files: Optimized JS/CSS for deployment

**.git/:**
- Purpose: Git repository metadata
- Generated: Yes (git init)
- Committed: Meta repository
- Notable: Recent commits track feature additions and testing infrastructure

**.planning/:**
- Purpose: GSD orchestration files and analysis documents
- Generated: Yes (via /gsd commands)
- Committed: Yes (tracked in git)
- Structure: `codebase/` contains ARCHITECTURE.md, STRUCTURE.md, etc.

---

*Structure analysis: 2026-02-04*