phase8: expand test coverage and refine docs with gitflow milestones
This commit is contained in:
Alfredo Di Stasio
163
README.md
163
README.md
@ -1,112 +1,185 @@
|
||||
# HoopScout
|
||||
|
||||
Production-minded basketball scouting and player search platform built with Django, HTMX, PostgreSQL, Redis, Celery, and nginx.
|
||||
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.
|
||||
|
||||
## Stack
|
||||
## Core Stack
|
||||
|
||||
- Python 3.12+
|
||||
- Django + Django Templates + HTMX (server-rendered)
|
||||
- Django
|
||||
- Django Templates + HTMX
|
||||
- PostgreSQL
|
||||
- Redis
|
||||
- Celery + Celery Beat
|
||||
- nginx
|
||||
- Django REST Framework (read-only API)
|
||||
- pytest
|
||||
- Docker / Docker Compose
|
||||
- nginx
|
||||
|
||||
## Project Structure
|
||||
## 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/
|
||||
│ ├── core/
|
||||
│ ├── users/
|
||||
│ ├── players/
|
||||
│ ├── api/
|
||||
│ ├── competitions/
|
||||
│ ├── teams/
|
||||
│ ├── stats/
|
||||
│ ├── scouting/
|
||||
│ ├── core/
|
||||
│ ├── ingestion/
|
||||
│ ├── players/
|
||||
│ ├── providers/
|
||||
│ └── ingestion/
|
||||
│ ├── scouting/
|
||||
│ ├── stats/
|
||||
│ ├── teams/
|
||||
│ └── users/
|
||||
├── config/
|
||||
│ └── settings/
|
||||
├── nginx/
|
||||
├── requirements/
|
||||
├── static/
|
||||
├── templates/
|
||||
└── tests/
|
||||
├── tests/
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
└── entrypoint.sh
|
||||
```
|
||||
|
||||
## Setup
|
||||
## Quick Start
|
||||
|
||||
1. Copy environment file:
|
||||
1. Create local env file:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
2. Build and start services:
|
||||
2. Build and run services:
|
||||
|
||||
```bash
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
3. Apply migrations (if auto-migrate disabled):
|
||||
3. If `AUTO_APPLY_MIGRATIONS=0`, run migrations manually:
|
||||
|
||||
```bash
|
||||
docker compose exec web python manage.py migrate
|
||||
```
|
||||
|
||||
4. Create superuser:
|
||||
4. Create a superuser:
|
||||
|
||||
```bash
|
||||
docker compose exec web python manage.py createsuperuser
|
||||
```
|
||||
|
||||
5. Access app:
|
||||
5. Open the app:
|
||||
|
||||
- Application: http://localhost
|
||||
- Web: http://localhost
|
||||
- Admin: http://localhost/admin/
|
||||
- Health endpoint: http://localhost/health/
|
||||
- Health: http://localhost/health/
|
||||
- API root endpoints: `/api/players/`, `/api/competitions/`, `/api/teams/`, `/api/seasons/`
|
||||
|
||||
## Authentication Routes
|
||||
## Setup and Run Notes
|
||||
|
||||
- Signup: `/users/signup/`
|
||||
- Login: `/users/login/`
|
||||
- Logout: `/users/logout/`
|
||||
- Dashboard (auth required): `/dashboard/`
|
||||
- `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.
|
||||
|
||||
## Tailwind Integration Strategy
|
||||
## Docker Volumes and Persistence
|
||||
|
||||
Phase 2 keeps styling minimal and framework-neutral using `static/css/main.css`.
|
||||
For upcoming phases, Tailwind will be integrated as a build step that emits compiled CSS into `static/css/` (e.g., via standalone Tailwind CLI or PostCSS in a dedicated frontend tooling container), while templates stay server-rendered.
|
||||
`docker-compose.yml` uses named volumes:
|
||||
|
||||
## Development Commands
|
||||
- `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)
|
||||
|
||||
Run tests:
|
||||
|
||||
```bash
|
||||
docker compose exec web pytest
|
||||
```
|
||||
|
||||
Run Django shell:
|
||||
|
||||
```bash
|
||||
docker compose exec web python manage.py shell
|
||||
```
|
||||
This keeps persistent state outside container lifecycles.
|
||||
|
||||
## Migrations
|
||||
|
||||
Create migration:
|
||||
Create migration files:
|
||||
|
||||
```bash
|
||||
docker compose exec web python manage.py makemigrations
|
||||
```
|
||||
|
||||
Apply migration:
|
||||
Apply migrations:
|
||||
|
||||
```bash
|
||||
docker compose exec web python manage.py migrate
|
||||
```
|
||||
|
||||
## GitFlow
|
||||
## Testing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for branch model and PR workflow.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user