HoopScout v2

HoopScout v2 is a Django/PostgreSQL scouting application developed through a repository-first workflow. The repo keeps both implementation guidance and Codex collaboration rules in version control so the project stays portable across machines.

Current MVP

The current application baseline provides:

• containerized local development
• curated sample seed data for manual exploration
• player scouting search with player, context, and stat filters
• wingspan-aware player filtering (min_wingspan_cm / max_wingspan_cm)
• matching season/team/competition context on search results
• result sorting and pagination
• login/logout with Django built-in authentication
• user-scoped shortlist favorites
• user-scoped plain-text scouting notes on player detail pages
• user-scoped saved searches (save, rerun, delete)
• first real-data ingestion command baseline (import_hoopdata_demo_competition) with idempotent source-identity mapping
• first public European importer (import_lba_public_serie_a) for LBA Serie A player-stat scope with idempotent external-ID binding

Accepted technical and product-shaping decisions live in:

• docs/ARCHITECTURE.md
• docs/ARCHITECTURE_PRINCIPLES.md
• docs/DECISION_PROCESS.md
• docs/adr/

Repository Structure

.
|-- .codex/
|-- .agents/skills/
|-- app/
|   |-- hoopscout/
|   `-- scouting/
|-- docs/
|-- infra/
|-- scripts/
|-- tests/
|-- AGENTS.md
|-- Makefile
`-- README.md

• app/hoopscout/ contains the Django project settings and root URLs.
• app/scouting/ contains the scouting domain models, views, templates, management commands, and tests tied to the app.
• infra/ contains the local Docker Compose and image setup.
• docs/ contains workflow and ADR documentation.
• scripts/ contains repository checks such as make doctor.

Local Development

1. Start the stack with docker compose --env-file .env -f infra/docker-compose.yml up -d --build.
2. Apply migrations with docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py migrate.
3. Load sample data with docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py seed_scouting_data.
4. Create a local user with docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py createsuperuser if you need a development login.
5. Visit http://127.0.0.1:8000/players/ to explore the scouting search MVP.
6. Use player-level filters (including wingspan), context filters, and stat filters to run scouting searches with sorting and pagination.
7. Log in at http://127.0.0.1:8000/accounts/login/ to manage your own shortlist, notes, and saved searches.
8. Save useful filter combinations from the player search page, rerun them later, or delete them.
9. Open player detail pages to review context rows and create user-scoped notes.
10. Use http://127.0.0.1:8000/favorites/ to review your user-scoped shortlist.

First real-data importer (ADR-0009 baseline):

• default sample snapshot import: docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py import_hoopdata_demo_competition
• explicit input path import: docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py import_hoopdata_demo_competition --input /app/scouting/sample_data/imports/hoopdata_demo_serie_a2_2025_2026.json

First public European importer (LBA Serie A scope):

• live public-source import (season start year 2025): docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py import_lba_public_serie_a --season 2025
• deterministic local-fixture import: docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py import_lba_public_serie_a --season 2025 --fixture /app/scouting/sample_data/imports/lba_public_serie_a_fixture.json

Legacy shared favorites and notes from the pre-auth MVP are cleared by the early-stage ownership migration so the app can move cleanly to user-scoped data.

Workflow

• main is the stable branch.
• develop is the integration branch.
• normal work goes through feature/* branches created from develop.
• run make doctor before or during local setup to confirm the repository foundation is present.

Durable project behavior belongs in the repository, especially:

• AGENTS.md
• .codex/
• .agents/skills/
• docs/

Local-only responsibilities still include authentication, personal editor setup, shell aliases, and secrets.

Contributing

• read AGENTS.md
• read docs/WORKFLOW.md
• read the current ADR set in docs/adr/
• create a task branch from develop
• keep tasks narrowly scoped and aligned with accepted decisions

License

License is currently unspecified.