186 lines
4.1 KiB
Markdown
186 lines
4.1 KiB
Markdown
# HoopScout
|
|
|
|
HoopScout is a production-minded basketball scouting and player search platform.
|
|
The main product experience is server-rendered Django Templates with HTMX enhancements.
|
|
A minimal read-only API is included as a secondary integration surface.
|
|
|
|
## Core Stack
|
|
|
|
- Python 3.12+
|
|
- Django
|
|
- Django Templates + HTMX
|
|
- PostgreSQL
|
|
- Redis
|
|
- Celery + Celery Beat
|
|
- Django REST Framework (read-only API)
|
|
- pytest
|
|
- Docker / Docker Compose
|
|
- nginx
|
|
|
|
## Architecture Summary
|
|
|
|
- Main UI: Django + HTMX (not SPA)
|
|
- Data layer: normalized domain models for players, seasons, competitions, teams, stats, scouting state
|
|
- Provider integration: adapter-based abstraction in `apps/providers`
|
|
- Ingestion orchestration: `apps/ingestion` with run/error logs and Celery task execution
|
|
- Optional API: read-only DRF endpoints under `/api/`
|
|
|
|
## Repository Structure
|
|
|
|
```text
|
|
.
|
|
├── apps/
|
|
│ ├── api/
|
|
│ ├── competitions/
|
|
│ ├── core/
|
|
│ ├── ingestion/
|
|
│ ├── players/
|
|
│ ├── providers/
|
|
│ ├── scouting/
|
|
│ ├── stats/
|
|
│ ├── teams/
|
|
│ └── users/
|
|
├── config/
|
|
│ └── settings/
|
|
├── nginx/
|
|
├── requirements/
|
|
├── static/
|
|
├── templates/
|
|
├── tests/
|
|
├── docker-compose.yml
|
|
├── Dockerfile
|
|
└── entrypoint.sh
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
1. Create local env file:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
2. Build and run services:
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
3. If `AUTO_APPLY_MIGRATIONS=0`, run migrations manually:
|
|
|
|
```bash
|
|
docker compose exec web python manage.py migrate
|
|
```
|
|
|
|
4. Create a superuser:
|
|
|
|
```bash
|
|
docker compose exec web python manage.py createsuperuser
|
|
```
|
|
|
|
5. Open the app:
|
|
|
|
- Web: http://localhost
|
|
- Admin: http://localhost/admin/
|
|
- Health: http://localhost/health/
|
|
- API root endpoints: `/api/players/`, `/api/competitions/`, `/api/teams/`, `/api/seasons/`
|
|
|
|
## Setup and Run Notes
|
|
|
|
- `web` service starts through `entrypoint.sh` and waits for PostgreSQL readiness.
|
|
- `celery_worker` executes background sync work.
|
|
- `celery_beat` supports scheduled jobs (future scheduling strategy can be added per provider).
|
|
- nginx proxies web traffic and serves static/media volume mounts.
|
|
|
|
## Docker Volumes and Persistence
|
|
|
|
`docker-compose.yml` uses named volumes:
|
|
|
|
- `postgres_data`: PostgreSQL persistent database
|
|
- `static_data`: collected static assets
|
|
- `media_data`: user/provider media artifacts
|
|
- `runtime_data`: persistent runtime files (e.g., celery beat schedule, redis data)
|
|
|
|
This keeps persistent state outside container lifecycles.
|
|
|
|
## Migrations
|
|
|
|
Create migration files:
|
|
|
|
```bash
|
|
docker compose exec web python manage.py makemigrations
|
|
```
|
|
|
|
Apply migrations:
|
|
|
|
```bash
|
|
docker compose exec web python manage.py migrate
|
|
```
|
|
|
|
## Testing
|
|
|
|
Run all tests:
|
|
|
|
```bash
|
|
docker compose run --rm web sh -lc 'pip install -r requirements/dev.txt && pytest -q'
|
|
```
|
|
|
|
Run a focused module:
|
|
|
|
```bash
|
|
docker compose run --rm web sh -lc 'pip install -r requirements/dev.txt && pytest -q tests/test_api.py'
|
|
```
|
|
|
|
## Superuser and Auth
|
|
|
|
Create superuser:
|
|
|
|
```bash
|
|
docker compose exec web python manage.py createsuperuser
|
|
```
|
|
|
|
Default auth routes:
|
|
|
|
- Signup: `/users/signup/`
|
|
- Login: `/users/login/`
|
|
- Logout: `/users/logout/`
|
|
|
|
## Ingestion and Manual Sync
|
|
|
|
### Trigger via Django Admin
|
|
|
|
- Open `/admin/` -> `IngestionRun`
|
|
- Use admin actions:
|
|
- `Queue full MVP sync`
|
|
- `Queue incremental MVP sync`
|
|
- `Retry selected ingestion runs`
|
|
|
|
### Trigger from shell (manual)
|
|
|
|
```bash
|
|
docker compose exec web python manage.py shell
|
|
```
|
|
|
|
```python
|
|
from apps.ingestion.tasks import trigger_full_sync
|
|
trigger_full_sync.delay(provider_namespace="mvp_demo")
|
|
```
|
|
|
|
### Logs and diagnostics
|
|
|
|
- Run-level status/counters: `IngestionRun`
|
|
- Structured error records: `IngestionError`
|
|
- Provider entity mappings + diagnostic payload snippets: `ExternalMapping`
|
|
|
|
## GitFlow Reference
|
|
|
|
HoopScout uses strict GitFlow:
|
|
|
|
- `main`: production-ready
|
|
- `develop`: integration
|
|
- `feature/*`: features from `develop`
|
|
- `release/*`: stabilization from `develop`
|
|
- `hotfix/*`: urgent production fixes from `main`
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for practical examples and milestone planning.
|