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

.
├── 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:

cp .env.example .env

2. Build and run services:

docker compose up --build

3. If AUTO_APPLY_MIGRATIONS=0, run migrations manually:

docker compose exec web python manage.py migrate

4. Create a superuser:

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:

docker compose exec web python manage.py makemigrations

Apply migrations:

docker compose exec web python manage.py migrate

Testing

Run all tests:

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

Run a focused module:

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

Superuser and Auth

Create superuser:

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)

docker compose exec web python manage.py shell

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 for practical examples and milestone planning.