phase1: bootstrap containerized django stack and project scaffold

README.md

@@ -1,2 +1,102 @@
-# hoopscout
+# HoopScout
 
+Production-minded basketball scouting and player search platform built with Django, HTMX, PostgreSQL, Redis, Celery, and nginx.
+
+## Stack
+
+- Python 3.12+
+- Django + Django Templates + HTMX (no SPA)
+- PostgreSQL
+- Redis
+- Celery + Celery Beat
+- nginx
+- Docker / Docker Compose
+
+## Repository Structure
+
+```text
+.
+├── apps/
+├── config/
+├── nginx/
+├── requirements/
+├── templates/
+├── tests/
+├── docker-compose.yml
+├── Dockerfile
+└── entrypoint.sh
+```
+
+## Setup
+
+1. Copy environment file:
+
+```bash
+cp .env.example .env
+```
+
+2. Build and start services:
+
+```bash
+docker compose up --build
+```
+
+3. Apply migrations (if not using auto migrations):
+
+```bash
+docker compose exec web python manage.py migrate
+```
+
+4. Create superuser:
+
+```bash
+docker compose exec web python manage.py createsuperuser
+```
+
+5. Access app:
+
+- Application: http://localhost
+- Admin: http://localhost/admin/
+- Health endpoint: http://localhost/health/
+
+## Development Commands
+
+Run tests:
+
+```bash
+docker compose exec web pytest
+```
+
+Run Django shell:
+
+```bash
+docker compose exec web python manage.py shell
+```
+
+Collect static files:
+
+```bash
+docker compose exec web python manage.py collectstatic --noinput
+```
+
+## Migrations
+
+Create migration:
+
+```bash
+docker compose exec web python manage.py makemigrations
+```
+
+Apply migration:
+
+```bash
+docker compose exec web python manage.py migrate
+```
+
+## Ingestion / Sync (Phase Placeholder)
+
+Data provider ingestion flow will be added in a later phase with adapter-based provider isolation.
+
+## GitFlow
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for branch model and PR workflow.