nuzlocke-tracker/.beans/nuzlocke-tracker-9ngw--stats-screen.md

title, status, type, priority, created_at, updated_at

title	status	type	priority	created_at	updated_at
Stats Screen	todo	feature	normal	2026-02-07T19:19:40Z	2026-02-07T19:28:49Z

A dedicated stats page aggregating data across all runs. Accessible from the main navigation.

Sections

1. Run Overview

• Total runs, active runs, completed runs, failed runs
• Win rate (completed / (completed + failed), excluding active)
• Average run duration (started_at → completed_at for finished runs)
• Pie or bar chart: runs by game (using game.name / game.color)
• Pie or bar chart: runs by region (game.region)
• Pie or bar chart: runs by generation (game.generation)

2. Encounter Stats

• Total encounters across all runs
• Breakdown by status: caught / fainted / missed (counts + percentages)
• Catch rate: caught / total encounters
• Average encounters per run

3. Pokemon Rankings

• Top N most-caught Pokemon (by pokemon_id frequency across encounters with status=caught), showing sprite + name + count
• Top N most-encountered Pokemon (any status), same display
• Configurable N (default 5, expandable to 10/all)

4. Team & Deaths

• Total Pokemon caught, total deaths (caught with faint_level != null)
• Mortality rate: deaths / caught
• Most common death causes (death_cause field, grouped + counted, top 5)
• Average catch level, average faint level
• Type distribution of caught Pokemon (bar chart of pokemon.types, counted across all caught encounters)

Data Access

Option A — Frontend-only (compute from existing data)

The list-runs endpoint already returns all runs with encounters. Stats can be computed client-side by fetching all runs. This is simpler but won't scale well with many runs.

Option B — Dedicated backend endpoint (recommended for scale)

Add GET /api/stats that runs aggregate queries server-side and returns pre-computed stats. This is more work but performs better and keeps the frontend thin.

Recommendation: Start with Option A for simplicity. If performance becomes an issue, migrate to Option B.

UI Notes

• New route: /stats
• Add "Stats" link to the main nav/sidebar
• Use the existing StatCard component for top-level numbers
• Charts: consider a lightweight library (e.g., recharts) or simple CSS bar charts to avoid heavy dependencies
• Responsive grid layout matching the existing design system (dark mode support)

Checklist

• Add /stats route and page component
• Add "Stats" navigation link
• Fetch all runs with encounters (or add backend stats endpoint)
• Run Overview section (counts, win rate, duration)
• Encounter Stats section (caught/fainted/missed breakdown)
• Pokemon Rankings section (top caught, top encountered, expandable)
• Team & Deaths section (mortality, death causes, type distribution)
• Charts for region/generation/type breakdowns
• Responsive layout + dark mode styling