# 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

```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. 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.