hoopscout/README.md

HoopScout

Production-minded basketball scouting and player search platform built with Django, HTMX, PostgreSQL, Redis, Celery, and nginx.

Stack

• Python 3.12+
• Django + Django Templates + HTMX (server-rendered)
• PostgreSQL
• Redis
• Celery + Celery Beat
• nginx
• Docker / Docker Compose

Project Structure

.
├── apps/
│   ├── core/
│   ├── users/
│   ├── players/
│   ├── competitions/
│   ├── teams/
│   ├── stats/
│   ├── scouting/
│   ├── providers/
│   └── ingestion/
├── config/
│   └── settings/
├── nginx/
├── requirements/
├── static/
├── templates/
└── tests/

Setup

1. Copy environment file:

cp .env.example .env

2. Build and start services:

docker compose up --build

3. Apply migrations (if auto-migrate disabled):

docker compose exec web python manage.py migrate

4. Create superuser:

docker compose exec web python manage.py createsuperuser

5. Access app:

• Application: http://localhost
• Admin: http://localhost/admin/
• Health endpoint: http://localhost/health/

Authentication Routes

• Signup: /users/signup/
• Login: /users/login/
• Logout: /users/logout/
• Dashboard (auth required): /dashboard/

Tailwind Integration Strategy

Phase 2 keeps styling minimal and framework-neutral using static/css/main.css. For upcoming phases, Tailwind will be integrated as a build step that emits compiled CSS into static/css/ (e.g., via standalone Tailwind CLI or PostCSS in a dedicated frontend tooling container), while templates stay server-rendered.

Development Commands

Run tests:

docker compose exec web pytest

Run Django shell:

docker compose exec web python manage.py shell

Migrations

Create migration:

docker compose exec web python manage.py makemigrations

Apply migration:

docker compose exec web python manage.py migrate

GitFlow

See CONTRIBUTING.md for branch model and PR workflow.