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)

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

Start the stack with docker compose --env-file .env -f infra/docker-compose.yml up -d --build.
Apply migrations with docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py migrate.
Load sample data with docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py seed_scouting_data.
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.
Visit http://127.0.0.1:8000/players/ to explore the scouting search MVP.
Use player-level filters (including wingspan), context filters, and stat filters to run scouting searches with sorting and pagination.
Log in at http://127.0.0.1:8000/accounts/login/ to manage your own shortlist, notes, and saved searches.
Save useful filter combinations from the player search page, rerun them later, or delete them.
Open player detail pages to review context rows and create user-scoped notes.
Use http://127.0.0.1:8000/favorites/ to review your user-scoped shortlist.

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.