hoopscout/README.md

HoopScout v2 (Foundation Reset)

HoopScout v2 is a controlled greenfield rebuild inside the existing repository.

Current v2 foundation scope in this branch:

• Django + HTMX server-rendered app
• PostgreSQL as the only primary database
• nginx reverse proxy
• management-command-driven runtime operations
• static snapshot directories persisted via Docker named volumes

Out of scope in this step:

• domain model redesign
• snapshot importer implementation
• extractor implementation

Runtime Architecture (v2)

Runtime services are intentionally small:

• web (Django/Gunicorn)
• postgres (primary DB)
• nginx (reverse proxy + static/media serving)

No Redis/Celery services are part of the v2 default runtime topology. Legacy Celery/provider code is still in repository history/codebase but de-emphasized for v2.

Image Strategy

Compose builds and tags images as:

• registry.younerd.org/hoopscout/web:${APP_IMAGE_TAG:-latest}
• registry.younerd.org/hoopscout/nginx:${NGINX_IMAGE_TAG:-latest}

Reserved for future optional scheduler use:

• registry.younerd.org/hoopscout/scheduler:${APP_IMAGE_TAG:-latest}

Entrypoint Strategy

• web: entrypoint.sh
  • waits for PostgreSQL
  • optionally runs migrations/collectstatic
  • ensures snapshot directories exist
• nginx: nginx/entrypoint.sh
  • simple runtime entrypoint wrapper

Compose Files

• docker-compose.yml: production-minded baseline runtime (immutable image filesystem)
• docker-compose.dev.yml: development override with source bind mount for web
• docker-compose.release.yml: production settings override (DJANGO_SETTINGS_MODULE=config.settings.production)

Start development runtime

cp .env.example .env
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Start release-style runtime

docker compose -f docker-compose.yml -f docker-compose.release.yml up -d --build

Named Volumes

v2 runtime uses named volumes for persistence:

• postgres_data
• static_data
• media_data
• snapshots_incoming
• snapshots_archive
• snapshots_failed

Development override uses separate dev-prefixed volumes to avoid ownership collisions.

Environment Variables

Use .env.example as the source of truth.

Core groups:

• Django runtime/security vars
• PostgreSQL connection vars
• image tag vars (APP_IMAGE_TAG, NGINX_IMAGE_TAG)
• snapshot directory vars (SNAPSHOT_*)
• optional future scheduler vars (SCHEDULER_*)

Snapshot Storage Convention

Snapshot files are expected under:

• incoming: /app/snapshots/incoming
• archive: /app/snapshots/archive
• failed: /app/snapshots/failed

In this foundation step, directories are created and persisted but no importer/extractor is implemented yet.

Migration and Superuser Commands

docker compose exec web python manage.py migrate
docker compose exec web python manage.py createsuperuser

Health Endpoints

• app health: /health/
• nginx healthcheck proxies /health/ to web

GitFlow

Required branch model:

• main: production
• develop: integration
• feature/*, release/*, hotfix/*

This v2 work branch is:

• feature/hoopscout-v2-static-architecture

Notes on Legacy Layers

Legacy provider/Celery ingestion layers are not the default runtime path for v2 foundation. They are intentionally isolated until replaced by v2 snapshot ingestion commands in later tasks.