97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
# 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
|
|
|
|
Accepted technical and product-shaping decisions live in:
|
|
- `docs/ARCHITECTURE.md`
|
|
- `docs/ARCHITECTURE_PRINCIPLES.md`
|
|
- `docs/DECISION_PROCESS.md`
|
|
- `docs/adr/`
|
|
|
|
## Repository Structure
|
|
|
|
```text
|
|
.
|
|
|-- .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`
|
|
|
|
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.
|