122 lines
3.3 KiB
Markdown
122 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
|
|
```
|
|
|
|
### Start release-style runtime
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|