# Spec: Internal Match Game Analysis P0/P1 ## Objective Make an internal-match game result explain both the final numbers and how the game reached them. P0 exposes data already present in the detail response: objective events, complete team objectives, participant gold/GPM, and explicitly labelled kill participation. P1 projects Riot Match-V5 timeline frames into real 10- and 15-minute lane checkpoints and a unified event stream for kills and structures. The primary user is a tournament participant or organizer reviewing a completed game on desktop or mobile. Success means the user can identify the major objective sequence before reading ten player cards, compare lane state at 10/15 minutes, and trace kills and building events without mistaking unavailable data for zero. ## Approved Product Decisions - Place game flow immediately after the game summary and before detail tabs. - Render chart events as both visual markers and a keyboard-readable text list. - Keep the existing gold/XP toggle and runes/build experience. - Show tower, dragon, inhibitor, Baron, Rift Herald, Void Grub, and Elder Dragon totals; derive dragon type labels only when objective events are available. - Combine participant CS and economy instead of adding another wide table column. - Label kill participation explicitly as `KP`. - Replace final-state values in the lane tab with 10/15-minute checkpoints; default to 15 minutes and pair players by `teamPosition`, never array position. - Keep `objectiveEvents` for compatibility and add `timelineEvents` for the unified P1 stream. - Treat missing checkpoints and events as unavailable, not zero. - Do not add an opaque MVP/rating or new external data feed in this scope. ## Tech Stack - React 19, TypeScript 6, Recharts 3, Tailwind CSS 4, and daisyUI under `apps/web` - NestJS 11, TypeScript 5, Mongoose 9, and Jest under `apps/api` - Riot Match-V5 match and timeline payloads already cached in `RiotMatchModel` - Node's built-in test runner for pure web transformations ## Commands - Focused web tests: `pnpm --filter web test` - Web lint: `pnpm --filter web lint` - Web production build: `pnpm --filter web build:prod` - Focused API tests: `pnpm --filter api test -- --runInBand riot-match.service.spec.ts match-stats-fragment.builder.spec.ts community-stats.service.spec.ts` - API build: `pnpm --filter api build` - Development web server: `pnpm --filter web start:dev` ## Project Structure - `apps/web/src/pages/MatchGameDetailPage.tsx` owns the result summary, participant scoreboard, flow chart, and accessible event list. - `apps/web/src/components/InternalGameAnalysisTabs.tsx` owns the lane and build tabs. - `apps/web/src/lib/internal-match-timeline.ts` owns pure event normalization, labels, filtering, and chart projection. - `apps/web/src/lib/internal-game-matchups.ts` owns pure role pairing and checkpoint comparisons. - `apps/web/test/` contains Node unit tests for the pure web transformations. - `apps/api/src/modules/riot/` parses trusted fields from Riot match timelines. - `apps/api/src/modules/community-stats/match-stats-fragment.builder.ts` projects stored Riot payloads into cached internal-match records. - `apps/api/src/modules/community-stats/community-stats.service.ts` maps persisted records into the public detail response and versions response caches. - `apps/api/src/modules/global/database/schema.ts` defines persisted TypeScript shapes; nested `gameDetails` remains a Mongoose Mixed array. ## Data Contract Participant checkpoint data is additive and optional for legacy/fallback games: ```ts interface MatchStatsCheckpoint { timestamp: number; gold: number; cs: number; xp: number; kills: number; deaths: number; assists: number; } interface MatchStatsParticipantCheckpoints { at10?: MatchStatsCheckpoint; at15?: MatchStatsCheckpoint; } ``` Each detailed participant gains optional `participantId` and `checkpoints`. Each game gains optional `timelineEvents`, whose `type` is an existing objective type or `championKill`, `tower`, or `inhibitor`. Actor IDs, assists, monster subtype, and tower subtype are optional fields appropriate to the event type. For a 10/15-minute target, use the latest frame at or before the target only when it is less than one `frameInterval` old. Persist the actual selected timestamp. CS is `minionsKilled + jungleMinionsKilled`; checkpoint K/D/A includes champion-kill events through the selected timestamp. A game ending before a target has no value for that checkpoint. ## Code Style Keep timeline calculations independent from React and use discriminated event types with conservative fallbacks: ```ts const events = game.timelineEvents?.length ? game.timelineEvents : game.objectiveEvents; const checkpoint = participant.checkpoints?.at15; if (!checkpoint) return { kind: "unavailable" }; ``` Use existing semantic color tokens and square bordered panels. Dynamic chart coordinates may use numeric props; spacing, colors, and typography remain in the existing Tailwind/daisyUI system. ## Testing Strategy - Develop pure event normalization, checkpoint selection, role pairing, and metric comparison test-first. - Builder tests cover exact and missing checkpoints, jungle CS, cumulative K/D/A, executes, objective fallback, building ownership, and deterministic event order. - Service tests reject stale cached response shapes and verify additive mapping. - Browser verification covers 320px, 390px, 768px, 1024px, and 1440px; the event text list is the accessible equivalent of decorative chart markers. - Verify the supplied production-like game as well as a short game and a game with no timeline. ## Boundaries ### Always - Preserve existing `objectiveEvents`, runes/builds, and match-detail routes. - Derive participant checkpoint values from stored Riot timeline frames. - Pair lanes by normalized `teamPosition` and show unavailable states explicitly. - Communicate team/event meaning with text as well as color. - Increment the match-stats builder and detail-response cache versions whenever a persisted or cached response shape changes. ### Ask First - Add a frontend or backend dependency. - Change the public route or remove compatibility fields. - Add a database migration or make a bulk external Riot API fetch. - Deploy, push, or alter CI configuration. ### Never - Infer absent checkpoint data as zero. - Pair opponents by array order. - Claim that a nearby objective caused a gold swing. - Expose unparsed arbitrary Riot event fields. - Modify unrelated Competition/bracket work already present in the worktree. ## Success Criteria - Game flow appears before player details and includes objective markers plus an equivalent textual sequence on desktop and mobile. - Summary shows all currently projected objective totals and available dragon types. - Every participant shows labelled KP, gold, GPM, CS, and CS/min without breaking the responsive scoreboard. - The lane tab defaults to 15 minutes, can switch to 10 minutes, and presents GD/CSD/XPD and checkpoint K/D/A for correctly paired roles. - The unified timeline can filter and display objectives, champion kills, towers, and inhibitors, while falling back to objective-only data during rolling updates. - Focused API/web tests, lint, and production builds pass. ## Open Questions None. The user reviewed the P0/P1 task plan and requested implementation.