From c2112b9b740ac5a1e21240d8915c3c9c83e9ed7f Mon Sep 17 00:00:00 2001 From: Julian Tabel Date: Sat, 7 Feb 2026 20:28:59 +0100 Subject: [PATCH] Add detailed stats screen bean and remove scrapped beans Co-Authored-By: Claude Opus 4.6 --- ...locke-tracker-8j45--imrpove-seeing-data.md | 12 ---- .beans/nuzlocke-tracker-9ngw--stats-screen.md | 67 +++++++++++++++++++ ...eding-to-use-pokeapi-csv-data-via-git-s.md | 57 ---------------- 3 files changed, 67 insertions(+), 69 deletions(-) delete mode 100644 .beans/nuzlocke-tracker-8j45--imrpove-seeing-data.md create mode 100644 .beans/nuzlocke-tracker-9ngw--stats-screen.md delete mode 100644 .beans/nuzlocke-tracker-ya2a--refactor-seeding-to-use-pokeapi-csv-data-via-git-s.md diff --git a/.beans/nuzlocke-tracker-8j45--imrpove-seeing-data.md b/.beans/nuzlocke-tracker-8j45--imrpove-seeing-data.md deleted file mode 100644 index 6f4b55a..0000000 --- a/.beans/nuzlocke-tracker-8j45--imrpove-seeing-data.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -# nuzlocke-tracker-8j45 -title: Improve Seeding Data -status: draft -type: task -priority: normal -created_at: 2026-02-05T17:40:31Z -updated_at: 2026-02-05T18:28:37Z ---- - -Seeding data should result in more human readable, either by mapping human readable entries to the more machine readable entries (like kanto -> Kanto, old-rod -> Old Rod) or saving the more human readable instead of the more machine readable entry. - diff --git a/.beans/nuzlocke-tracker-9ngw--stats-screen.md b/.beans/nuzlocke-tracker-9ngw--stats-screen.md new file mode 100644 index 0000000..fc7badf --- /dev/null +++ b/.beans/nuzlocke-tracker-9ngw--stats-screen.md @@ -0,0 +1,67 @@ +--- +# nuzlocke-tracker-9ngw +title: Stats Screen +status: todo +type: feature +priority: normal +created_at: 2026-02-07T19:19:40Z +updated_at: 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 \ No newline at end of file diff --git a/.beans/nuzlocke-tracker-ya2a--refactor-seeding-to-use-pokeapi-csv-data-via-git-s.md b/.beans/nuzlocke-tracker-ya2a--refactor-seeding-to-use-pokeapi-csv-data-via-git-s.md deleted file mode 100644 index d2358dc..0000000 --- a/.beans/nuzlocke-tracker-ya2a--refactor-seeding-to-use-pokeapi-csv-data-via-git-s.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -# nuzlocke-tracker-ya2a -title: Refactor seeding to use PokeAPI CSV data via git submodule -status: draft -type: task -priority: normal -created_at: 2026-02-05T18:01:09Z -updated_at: 2026-02-05T18:06:04Z ---- - -## Summary - -Replace the current seeding approach (which uses the `pokebase` Python library to hit the PokeAPI REST API, then writes intermediate JSON files) with reading static JSON data from the [PokeAPI/api-data](https://github.com/PokeAPI/api-data) repository, pulled in as a git submodule. - -The `api-data` repo contains a static copy of the full PokeAPI output as JSON files at `data/api/v2/{endpoint}/{id}/index.json`, mirroring the REST API structure exactly. - -## Motivation - -- **Eliminates network dependency**: No more hitting the PokeAPI REST API (or running a local instance) during seed generation -- **Faster**: Reading local JSON files is instant vs. hundreds of HTTP requests (even with pokebase caching) -- **Minimal code change**: The JSON structure matches the API responses, so parsing logic stays similar to the current `fetch_pokeapi.py` -- **More data available**: The full dataset is available locally, not just what we query for -- **Version-pinnable**: The git submodule can be pinned to a specific commit for reproducible builds -- **Removes `pokebase` dependency**: One less runtime/dev dependency to maintain - -## Current Approach - -1. `fetch_pokeapi.py` uses the `pokebase` library to query the PokeAPI REST API -2. It processes responses and writes intermediate JSON files (`games.json`, `pokemon.json`, `firered.json`, etc.) to `seeds/data/` -3. `run.py` reads these JSON files and calls `loader.py` to upsert into the database -4. Evolution data is also fetched from the API with an override mechanism (`evolution_overrides.json`) - -## Proposed Approach - -1. **Add git submodule**: Add `https://github.com/PokeAPI/api-data` as a git submodule with `--depth 1` (e.g., at `data/pokeapi/` or `backend/pokeapi-data/`) -2. **Rewrite `fetch_pokeapi.py`**: Replace API calls with local JSON file reads from the submodule. The data lives at `data/api/v2/{endpoint}/{id}/index.json`. Key endpoints: - - `pokemon/{id}/` and `pokemon-species/{id}/` — Pokemon data & names - - `type/{id}/` — Type data - - `region/{id}/` — Region data with location refs - - `location/{id}/` — Locations with area refs - - `location-area/{id}/` — Location areas with encounter data - - `version/{id}/` and `version-group/{id}/` — Game/version data - - `evolution-chain/{id}/` — Evolution chain data -3. **Keep the same output format**: The rewritten script should still produce the same intermediate JSON files (`games.json`, `pokemon.json`, `firered.json`, etc.) so `run.py` and `loader.py` remain unchanged. -4. **Keep the override mechanism**: `evolution_overrides.json` should still work for manual corrections. -5. **Remove `pokebase` dependency**: Remove from `pyproject.toml` / `requirements.txt`. -6. **Update documentation**: Update any setup/dev docs and the seed run command instructions. - -## Checklist - -- [ ] Add `PokeAPI/api-data` repo as a git submodule (shallow clone) -- [ ] Rewrite `fetch_pokeapi.py` to read local JSON files from the submodule instead of calling the API -- [ ] Verify output JSON files match the current format (so `run.py`/`loader.py` stay unchanged) -- [ ] Preserve evolution override mechanism -- [ ] Remove `pokebase` dependency -- [ ] Test that seeding produces equivalent results -- [ ] Update dev setup docs / seed run instructions \ No newline at end of file