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
This commit is contained in:
Thomas Richter
161
.planning/codebase/INTEGRATIONS.md
Normal file
161
.planning/codebase/INTEGRATIONS.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user