nuzlocke-tracker

A full-stack Nuzlocke run tracker for Pokemon games.

Getting Started

Prerequisites

• Docker & Docker Compose

Start the Stack

docker compose up

This starts three services:

Service	URL
Frontend	http://localhost:5173
API	http://localhost:8000
API Docs	http://localhost:8000/docs
PostgreSQL	localhost:5432

Run Migrations

docker compose exec api alembic -c /app/alembic.ini upgrade head

Seed the Database

The seeder reads from pre-generated JSON files in backend/src/app/seeds/data/ (committed to the repo) and loads them into PostgreSQL. No external API access is needed — everything runs from local files inside the container.

docker compose exec api python -m app.seeds

To seed and verify the data was loaded correctly:

docker compose exec api python -m app.seeds --verify

This loads game data, Pokemon, routes, and encounter tables for FireRed, LeafGreen, Emerald, HeartGold, and SoulSilver.

Regenerating Seed Data

The seed JSON files don't normally need regenerating. If you need to update them (e.g., to pull in new PokeAPI data), run the Go fetch tool against a local PokeAPI instance:

1. Start a local PokeAPI (e.g., using pokeapi/pokeapi):

   # In a separate directory
   git clone https://github.com/PokeAPI/pokeapi.git && cd pokeapi
   docker compose up
   

   This serves the API at http://localhost:8000/api/v2 by default.

2. Run the fetch tool (requires Go 1.22+):

   cd tools/fetch-pokeapi && go run .
   

   Set POKEAPI_URL if your instance is at a different address:

   POKEAPI_URL=http://localhost:9000/api/v2 go run .
   

   Use --clear-cache to discard cached API responses and re-fetch everything.

3. Review and commit the updated JSON files in backend/src/app/seeds/data/.