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 PokeAPI data), run the Go fetch tool against a local PokeAPI instance:

1. Start a local PokeAPI (e.g., using [pokeapi/pokeapi](https://github.com/PokeAPI/pokeapi)):

   ```bash
   # 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+):

   ```bash
   cd tools/fetch-pokeapi && go run .
   ```

   Set `POKEAPI_URL` if your instance is at a different address:

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