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 is still a phase-1 architecture overview, but the repository now has its first accepted concrete technical decision in docs/adr/0001-runtime-and-development-stack.md. Later implementation work should follow that corrected baseline unless a future 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

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 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