nuzlocke-tracker/README.md

# nuzlocke-tracker

A full-stack Nuzlocke run tracker for Pokemon games.

## Getting Started

### Prerequisites

- Docker & Docker Compose

### Start the Stack

```bash
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

```bash
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.

```bash
docker compose exec api python -m app.seeds
```

To seed and verify the data was loaded correctly:

```bash
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 game data), run the import tool from the repo root:

```bash
python -m import_pokedb
```

It auto-downloads [PokeDB](https://pokedb.org) data on the first run. Options:

```bash
# Generate data for a specific game only
python -m import_pokedb --game firered

# Use a custom PokeDB data directory
python -m import_pokedb --pokedb-dir ~/my-pokedb-data/

# Write output to a different directory
python -m import_pokedb --output /tmp/seed-output/
```

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