Files
lolympus-tournament-support/docs/specs/internal-match-game-analysis.md
T

7.3 KiB

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:

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:

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.