# TipSharks Setup Guide

This guide covers the current TipSharks repository layout and CLI paths.

## Prerequisites

- Docker and Docker Compose (recommended for local runs)
- Optional for local dev: Python 3.12 and `pip`

## Quick Start (Docker)

### 1. Clone and Configure

```bash
git clone <repository-url>
cd tipsharks
cp .env.example .env
```

Set your admin token in `.env`:
```
API_ADMIN_TOKEN=change_me_in_production
```

### 2. Start Services

```bash
docker compose up -d
```

This launches:
- PostgreSQL on `localhost:5432`
- API + Web UI on `http://localhost:8000`

### 3. Run Migrations

```bash
docker compose run --rm worker alembic upgrade head
```

### 4. Verify Setup

```bash
docker compose run --rm worker python -m apps.backend.worker.cli info
```

### 5. Ingest Data

TAB API (public, no credentials required):
```bash
docker compose run --rm worker python -m apps.backend.worker.cli ingest \
  --from 2024-01-01 \
  --to 2024-01-31
```

Optional HRNZ InfoHorse scrape (Playwright runs in the API container):
```bash
curl -X POST http://localhost:8000/webhook/scrape \
  -H "Authorization: Bearer <API_ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "club_codes": "all",
    "date_from": "2024-01-01",
    "date_to": "2024-01-31",
    "recompute": true
  }'
```

### 6. Compute Ratings

```bash
docker compose run --rm worker python -m apps.backend.worker.cli recompute \
  --from 2024-01-01 \
  --to 2024-01-31
```

### 7. Access the UI

- Web UI: `http://localhost:8000/`
- API docs (Swagger): `http://localhost:8000/docs`
- Documentation site: `http://localhost:8000/docs/site/`

## Local Development (Optional)

```bash
python3.12 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
```

Run tests:
```bash
pytest
```

## Troubleshooting

### Database Connection Errors

```bash
docker compose ps
docker compose logs db
docker compose restart db
```

### Migrations Fail

```bash
docker compose run --rm worker alembic current
docker compose run --rm worker alembic upgrade head
```

### Ratings Not Appearing

```bash
docker compose exec db psql -U tipsharks -c "SELECT COUNT(*) FROM rating_snapshots;"
docker compose logs worker
```