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

title, status, type, priority, created_at, updated_at

title	status	type	priority	created_at	updated_at
Boss Battles, Level Caps & Badges	completed	feature	normal	2026-02-07T20:16:14Z	2026-02-08T11:23:58Z

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 — level cap calculated client-side from bosses list
• Bulk import endpoint or script for boss data — managed via admin UI + export endpoint

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 — managed via admin UI