nuzlocke-tracker/.beans/nuzlocke-tracker-kvmd--boss-battles-level-caps-badges.md

title, status, type, created_at, updated_at

title	status	type	created_at	updated_at
Boss Battles, Level Caps & Badges	draft	feature	2026-02-07T20:16:14Z	2026-02-07T20:16:14Z

Add boss battle tracking (Gym Leaders, Elite Four, Champion, rivals), badge progression, and level cap enforcement to the nuzlocke tracker.

Context

The levelCaps rule toggle exists but has no data or enforcement behind it. Boss battles are core progression milestones in any nuzlocke run — defeating them earns badges, unlocks level cap increases, and marks key story moments. This feature adds the data model, import tooling, and UI to support all of this.

Data Model

BossBattle (new model, per-game)

• id, game_id (FK)
• name (e.g. "Brock", "Cynthia", "Rival 1")
• boss_type — gym_leader, elite_four, champion, rival, evil_team, other
• badge_name (nullable, e.g. "Boulder Badge" — only for gym leaders)
• level_cap (SmallInteger — highest level on their team, used for level caps rule)
• order (SmallInteger — progression order within the game)
• location (string — where the fight happens, e.g. "Pewter City Gym")
• sprite_url (nullable — trainer sprite)

BossPokemon (new model, pokemon on a boss's team)

• id, boss_battle_id (FK)
• pokemon_id (FK)
• level (SmallInteger)
• order (SmallInteger — slot order)

BossResult (new model, per-run tracking of boss outcomes)

• id, run_id (FK), boss_battle_id (FK)
• result — won, lost
• attempts (int, default 1)
• deaths — list of encounter IDs that died during this fight (optional JSON or relation)
• completed_at (datetime)

Checklist

Backend

• Migration: Create boss_battles, boss_pokemon, and boss_results tables
• Models: BossBattle, BossPokemon, BossResult
• Schemas: Create/Response schemas for all three models
• API: CRUD endpoints for boss_battles (admin — per game)
• API: GET /games/{game_id}/bosses — list all bosses for a game with their pokemon teams
• API: POST /runs/{run_id}/boss-results — log a boss fight result
• API: GET /runs/{run_id}/boss-results — get all boss results for a run
• API: GET /runs/{run_id}/level-cap — return current level cap based on next undefeated boss
• Bulk import endpoint or script for boss data (like pokemon bulk-import)

Frontend

• Types: BossBattle, BossPokemon, BossResult interfaces
• API + hooks: Fetch bosses, log results, get level cap
• Boss progression section on RunEncounters page — show next boss, badges earned, level cap
• Badge display: row of earned/unearned badge icons (greyed out until defeated)
• Level cap indicator: show current cap prominently when levelCaps rule is on, highlight team members over the cap
• Boss battle log modal: record fight result, mark deaths that occurred during the fight
• Boss detail view: show boss's team with pokemon sprites and levels

Data

• Seed boss data for at least one game (e.g. FireRed/LeafGreen or the game currently being tested)