# HoopScout

HoopScout is a production-minded basketball scouting and player search platform.
The main product experience is server-rendered Django Templates with HTMX enhancements.
A minimal read-only API is included as a secondary integration surface.

## Core Stack

- Python 3.12+
- Django
- Django Templates + HTMX
- PostgreSQL
- Redis
- Celery + Celery Beat
- Django REST Framework (read-only API)
- pytest
- Docker / Docker Compose
- nginx

## Architecture Summary

- Main UI: Django + HTMX (not SPA)
- Data layer: normalized domain models for players, seasons, competitions, teams, stats, scouting state
- Provider integration: adapter-based abstraction in `apps/providers`
- Ingestion orchestration: `apps/ingestion` with run/error logs and Celery task execution
- Optional API: read-only DRF endpoints under `/api/`

## Repository Structure

```text
.
├── apps/
│   ├── api/
│   ├── competitions/
│   ├── core/
│   ├── ingestion/
│   ├── players/
│   ├── providers/
│   ├── scouting/
│   ├── stats/
│   ├── teams/
│   └── users/
├── config/
│   └── settings/
├── nginx/
├── requirements/
├── static/
├── templates/
├── tests/
├── docker-compose.yml
├── Dockerfile
└── entrypoint.sh
```

## Quick Start

1. Create local env file:

```bash
cp .env.example .env
```

2. Build and run services:

```bash
docker compose up --build
```

3. If `AUTO_APPLY_MIGRATIONS=0`, run migrations manually:

```bash
docker compose exec web python manage.py migrate
```

4. Create a superuser:

```bash
docker compose exec web python manage.py createsuperuser
```

5. Open the app:

- Web: http://localhost
- Admin: http://localhost/admin/
- Health: http://localhost/health/
- API root endpoints: `/api/players/`, `/api/competitions/`, `/api/teams/`, `/api/seasons/`

## Setup and Run Notes

- `web` service starts through `entrypoint.sh` and waits for PostgreSQL readiness.
- `celery_worker` executes background sync work.
- `celery_beat` supports scheduled jobs (future scheduling strategy can be added per provider).
- nginx proxies web traffic and serves static/media volume mounts.

## Docker Volumes and Persistence

`docker-compose.yml` uses named volumes:

- `postgres_data`: PostgreSQL persistent database
- `static_data`: collected static assets
- `media_data`: user/provider media artifacts
- `runtime_data`: persistent runtime files (e.g., celery beat schedule, redis data)

This keeps persistent state outside container lifecycles.

## Migrations

Create migration files:

```bash
docker compose exec web python manage.py makemigrations
```

Apply migrations:

```bash
docker compose exec web python manage.py migrate
```

## Testing

Run all tests:

```bash
docker compose run --rm web sh -lc 'pip install -r requirements/dev.txt && pytest -q'
```

Run a focused module:

```bash
docker compose run --rm web sh -lc 'pip install -r requirements/dev.txt && pytest -q tests/test_api.py'
```

## Superuser and Auth

Create superuser:

```bash
docker compose exec web python manage.py createsuperuser
```

Default auth routes:

- Signup: `/users/signup/`
- Login: `/users/login/`
- Logout: `/users/logout/`

## Ingestion and Manual Sync

### Trigger via Django Admin

- Open `/admin/` -> `IngestionRun`
- Use admin actions:
  - `Queue full MVP sync`
  - `Queue incremental MVP sync`
  - `Retry selected ingestion runs`

### Trigger from shell (manual)

```bash
docker compose exec web python manage.py shell
```

```python
from apps.ingestion.tasks import trigger_full_sync
trigger_full_sync.delay(provider_namespace="mvp_demo")
```

### Logs and diagnostics

- Run-level status/counters: `IngestionRun`
- Structured error records: `IngestionError`
- Provider entity mappings + diagnostic payload snippets: `ExternalMapping`

## GitFlow Reference

HoopScout uses strict GitFlow:

- `main`: production-ready
- `develop`: integration
- `feature/*`: features from `develop`
- `release/*`: stabilization from `develop`
- `hotfix/*`: urgent production fixes from `main`

See [CONTRIBUTING.md](CONTRIBUTING.md) for practical examples and milestone planning.