hoopscout-v2/README.md

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
• 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

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