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
matching season/team/competition context on search results
result sorting and pagination
a shared development shortlist for favorite players
shared plain-text scouting notes on player detail pages

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.
Visit http://127.0.0.1:8000/players/ to explore the scouting search MVP.
Use player detail pages to manage shortlist entries and shared scouting notes.
Use http://127.0.0.1:8000/favorites/ to review the shared development shortlist.

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.