hoopscout-v2/docs/ARCHITECTURE.md

Architecture

Purpose

This document will become the central architecture overview for HoopScout v2. It should summarize the current approved technical direction and provide a stable starting point for future implementation work.

Current Status

This architecture overview summarizes the accepted technical and domain-decision baseline for implementation. Future model, filter, and UI work should follow the current ADR set unless a later ADR supersedes it.

Decision-Driven Development

Architecture in this repository should be decision-driven. Major technical choices should be documented before implementation begins, and implementation should follow documented decisions rather than informal local reasoning.

Relationship to Architecture Principles

This document should stay consistent with docs/ARCHITECTURE_PRINCIPLES.md. Future architecture sections should reflect the guiding principles and constraints defined there before they commit the repository to more concrete technical choices.

Relationship to ADRs

This document should stay aligned with the ADR set in docs/adr/. ADRs capture specific decisions and their rationale. This overview should summarize the accepted decisions at a higher level, not replace the ADR record.

The current baseline decision is:

• ADR-0001: runtime and development stack baseline
• ADR-0002: initial project structure baseline
• ADR-0003: containerized developer workflow baseline
• ADR-0004: configuration and environment strategy baseline
• ADR-0005: scouting search-domain baseline
• ADR-0006: initial domain-model baseline

The current baseline assumes:

• Python 3
• Django
• PostgreSQL
• containerized local development by default

Future implementation work should assume the containerized workflow and PostgreSQL baseline rather than introducing non-containerized local setups or a different default database.

Future scaffolding and implementation work should also follow the initial repository structure defined in docs/adr/0002-initial-project-structure.md unless a later ADR supersedes it.

Future runtime and scaffolding work should also follow the developer workflow defined in docs/adr/0003-containerized-developer-workflow.md, including app and PostgreSQL containers as the baseline local services and container-run development commands by default.

Future scaffolding should also follow the configuration strategy defined in docs/adr/0004-configuration-and-environment-strategy.md, including environment-variable based configuration, a repository-owned .env.example, local-only secrets, and a simple initial Django settings approach unless a later ADR supersedes it.

Future search model/filter/UI implementation should follow the domain semantics defined in docs/adr/0005-scouting-search-domain.md, including the separation of position vs role vs specialty, MVP filter scope, and optional vs required dimensions.

Future Django domain model work should follow docs/adr/0006-initial-domain-model.md as the baseline entity/relationship decision (including player-season stat ownership and taxonomy treatment) unless superseded by a later ADR.

Future Sections Placeholder

Future versions of this document may include sections such as:

• system context
• major components
• data flow
• deployment/runtime assumptions
• integration boundaries
• operational considerations