docs: map existing codebase

- STACK.md - Technologies and dependencies - ARCHITECTURE.md - System design and patterns - STRUCTURE.md - Directory layout - CONVENTIONS.md - Code style and patterns - TESTING.md - Test structure - INTEGRATIONS.md - External services - CONCERNS.md - Technical debt and issues
2026-02-04 23:16:04 +01:00
parent 24a44583ef
commit 576799ae0e
7 changed files with 1265 additions and 0 deletions
--- a/.planning/codebase/STRUCTURE.md
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,177 @@
+# 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*