---
# nuzlocke-tracker-kvmd
title: Boss Battles, Level Caps & Badges
status: draft
type: feature
created_at: 2026-02-07T20:16:14Z
updated_at: 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)