hoopscout-v3/docs/architecture.md

Architecture

HoopScout is a private scouting application composed of three local Docker services:

• frontend: Angular single-page application for player search and profile review.
• backend: Django REST Framework API with Django admin for restricted data management.
• db: PostgreSQL database for users, leagues, teams, players, season stats, and game logs.

Data Flow

Users authenticate through Django session/basic authentication. The Angular application calls /api/players/ with search and filter query parameters. The backend returns paginated player summaries ranked by efficiency and points, plus detailed player profiles at /api/players/{id}/.

Persistence

The initial schema stores:

• users and user profiles with admin, scout, and viewer roles;
• male player identity, bio, position, optional role, measurements in cm/kg, nationality, current team, and external source metadata;
• leagues and teams, with an initial focus on European leagues;
• one active season;
• per-season averages, totals, and advanced metrics;
• per-game logs for best and worst performance views.

The Angular dashboard applies filters only when the user refreshes the result set, then supports local stat sorting, summary metrics, and an open/close profile panel on desktop.

External Integrations

No automated external ingestion is included in the MVP. Demo data is synthetic and intentionally broad enough for UI testing. RealGM, Proballers, or similar data providers require a later authorized API/import decision before real data is collected.

Relevant ADRs

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