hoopscout-v3/docs/adr/0001-bootstrap-stack-and-data-boundaries.md

ADR-0001: Bootstrap Stack and Data Boundaries

Date: 2026-06-03

Status: Accepted

Context

HoopScout needs a private MVP for scouting male basketball players, initially focused on European leagues and a single season. The requested stack is Docker, Django, PostgreSQL, and Angular. Development must follow pragmatic TDD and keep implementation choices simple.

External sources such as RealGM and Proballers may be useful, but the project does not yet have authorized API credentials, provider terms review, or a data license.

Decision

Use Docker Compose with:

• Django REST Framework for the backend API and Django admin;
• PostgreSQL for persistent relational data;
• Angular for the scouting dashboard;
• synthetic demo data through a Django management command;
• authenticated API access through Django session/basic authentication;
• user profile roles modeled as admin, scout, and viewer.

Do not add automated scraping or copied external datasets in the MVP. Keep provider metadata fields so future authorized imports can preserve source references.

Consequences

The MVP can be run locally and tested inside containers with a small, understandable architecture. The schema supports player identity, position, optional role, league, team, season averages, totals, advanced statistics, and best/worst game summaries.

Real data ingestion remains a later feature and must be designed around provider authorization and licensing.

Alternatives considered

• Scrape RealGM or Proballers immediately: rejected because provider authorization and terms are not yet documented.
• Add JWT authentication immediately: deferred because Django session/basic authentication is enough for local restricted use.
• Add notes, exports, and watchlists immediately: deferred because they are outside the initial MVP scope.

Security impact

All API endpoints require authentication. Secrets are read from environment variables and .env is ignored by Git. Containers use non-root users where practical. PostgreSQL is not exposed outside the Compose network.

Operational impact

The application is local-only. Production deployment, TLS, backup automation, stricter role permissions, and source ingestion jobs require later ADRs.

Rollback

Revert the bootstrap commit and remove local Docker volumes if database state can be discarded.