# Feature Context: Game Integration

## Configuration
- **Development mode:** Automated
- **Execution mode:** Orchestrator
- **Strategy:** Big Bang
- **Build (frontend):** `cd server && npm run build`
- **Test:** `cd server && py -3.13 -m pytest tests/ --no-cov -q`
- **Lint:** `cd server && ruff check src/ tests/ --fix`
- **TypeScript:** `cd server && npx tsc --noEmit`

## Architecture Decisions

### Not a Capture Engine
Game events are discrete data points, not pixel buffers. The integration lives as a separate `core/game_integration/` module with two output channels into existing pipelines:
1. `GameEventColorStripSource/Stream` — renders LED effects on game events
2. `GameEventValueSource` — exposes game metrics as 0.0-1.0 scalars for parameter binding

### Standardized Event Vocabulary
All adapters map game-specific data into universal event categories (health, kill, death, round_start, etc.). Users configure effects against categories, not game-specific IDs. This means a "health < 30% → flash red" config works across CS2, LoL, and any future game.

### Three Adapter Tiers
1. **Built-in** — CS2 GSI, LoL Live Client, Dota 2 GSI, generic webhook (ship with app)
2. **Community YAML** — declarative adapter files mapping JSON paths to standard events (no code)
3. **Generic webhook** — fallback with UI-guided JSON path mapping

### Event Types
- **Continuous** (health, armor, mana, ammo) → best for ValueSource (drive brightness/speed/color)
- **Trigger** (kill, death, round_start, bomb_planted) → best for ColorStripStream (fire effects)

## Tech Stack Context

### Backend Patterns (from codebase analysis)
- **Entity pattern**: dataclass model (`storage/`) + JSON/SQLite store (`storage/*_store.py`) + Pydantic schemas (`api/schemas/`) + routes (`api/routes/`)
- **Store base**: `BaseSqliteStore[T]` with write-through cache, RLock, `_check_name_unique()`
- **ID generation**: `f"{prefix}_{uuid.uuid4().hex[:8]}"`
- **Events**: `fire_entity_event(entity_type, action, entity_id)` for UI invalidation
- **ColorStripSource**: inheritance with `_SOURCE_TYPE_MAP` registry, `to_dict()`/`from_dict()`/`create_from_kwargs()`/`apply_update()`
- **ColorStripStream**: `_SIMPLE_STREAM_MAP` in `color_strip_stream_manager.py`
- **ValueSource**: similar inheritance with `_VALUE_SOURCE_MAP` registry
- **NotificationColorStripStream**: closest analog — event-driven, deque + lock, 30 FPS render loop, double-buffered output
- **Bindable**: `BindableFloat`/`BindableColor` for value source parameter binding
- **Dependencies**: `init_dependencies()` in `dependencies.py`, FastAPI `Depends()`
- **STORE_MAP**: in `api/routes/system.py` for backup/restore

### Frontend Patterns
- Vanilla TypeScript modules, no framework
- `CardSection` for entity lists with reconciliation
- `Modal` base class with `snapshotValues()` for dirty check
- `TreeNav` for sidebar navigation in Streams tab
- `DataCache` for state management
- `fetchWithAuth()` for all API calls
- `t('key')` for i18n, keys in en.json/ru.json/zh.json
- `fire_entity_event` → frontend listens for cache invalidation
- Icons from `core/icons.ts` (SVG paths), NEVER emoji
- `IconSelect` for predefined item grids, `EntitySelect` for entity references

## Current State
Feature not yet started. Branch created, plan files written.

## Temporary Workarounds
None yet.

## Cross-Phase Dependencies
- Phase 2 depends on Phase 1 (EventBus, AdapterRegistry)
- Phase 3 depends on Phase 1 (GameAdapter ABC, MappingAdapter)
- Phase 4 depends on Phase 1 (EventBus) and Phase 2 (GameIntegrationStore for config)
- Phase 5 depends on Phase 1 (EventBus) and Phase 2 (GameIntegrationStore)
- Phase 6 depends on Phase 2 (API endpoints) and Phase 3 (adapter metadata)
- Phase 7 depends on Phase 4 (CSS source type) and Phase 5 (value source type)
- Phase 8 depends on all prior phases
- **Phases 4 and 5 are independent** — can run in parallel

## Deferred Work
None yet.

## Failed Approaches
None yet.

## Review Findings Log
None yet.

## Phase Execution Log
| Phase | Agent Used | Test Writer | Parallel | Notes |
|-------|-----------|-------------|----------|-------|