ledgrab/plans/game-integration/CONTEXT.md

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