Merge branch 'feature/phase-1-runtime-stack-decision' into develop

docs/ARCHITECTURE.md

@@ -6,7 +6,7 @@ This document will become the central architecture overview for HoopScout v2. It
 
 ## Current Status
 
-This is a phase-1 placeholder. The architecture is not yet fully defined, and implementation should not proceed from undocumented assumptions.
+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 baseline unless a future ADR supersedes it.
 
 ## Decision-Driven Development
 
@@ -20,6 +20,9 @@ This document should stay consistent with `docs/ARCHITECTURE_PRINCIPLES.md`. Fut
 
 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
+
 ## Future Sections Placeholder
 
 Future versions of this document may include sections such as:

docs/adr/0001-runtime-and-development-stack.md

@@ -0,0 +1,84 @@
+# ADR-0001: Runtime and Development Stack
+
+- Status: accepted
+- Date: 2026-03-20
+
+## Context
+
+HoopScout v2 is moving from phase-1 decision framing toward implementation guidance. The project needs one explicit baseline runtime and development stack decision so future implementation prompts do not depend on undocumented assumptions.
+
+The chosen baseline should fit the current architecture principles:
+- keep the stack small and maintainable
+- preserve portability across machines
+- avoid unnecessary operational complexity
+- support fast iteration and learning
+
+This decision covers:
+- programming language and runtime family
+- web application framework direction
+- persistence direction
+- whether containerization is part of the baseline developer workflow
+- acceptable operational complexity for the current stage
+
+## Decision
+
+Use the following baseline unless a future ADR supersedes it:
+
+- language/runtime family: Python 3
+- web application framework direction: Django with a single deployable application by default
+- persistence direction: SQLite for the initial baseline and local development workflow
+- containerization: not part of the baseline developer workflow in the current phase
+- operational complexity: keep it low; default to one application process and the simplest local setup that supports iteration
+
+This baseline is intentionally conservative. It favors a familiar, batteries-included web framework and a minimal local setup over early complexity.
+
+## Alternatives Considered
+
+### Option A: Python 3 + Django + SQLite + no baseline containerization
+
+Chosen.
+
+### Option B: Python 3 + FastAPI + SQLAlchemy + PostgreSQL + optional containers
+
+Not chosen. This could be a valid direction later, but it introduces more upfront assembly and more moving parts before the project has established concrete application needs.
+
+### Option C: JavaScript/TypeScript full-stack baseline with Node.js, a web framework, and a separate database
+
+Not chosen. This remains possible in theory, but it would add a broader stack decision surface and more early choices than the current phase needs.
+
+## Trade-Offs
+
+Evaluation against the standard decision criteria:
+
+- simplicity: strong fit; Django and SQLite keep the baseline small and reduce early setup choices
+- portability: strong fit; Python and SQLite are workable across machines without assuming containers
+- maintainability: good fit; the baseline favors a conventional, well-documented structure over novelty
+- operational complexity: strong fit; no baseline container dependency and no multi-service assumption
+- testability: good fit; Django provides established testing support for early implementation work
+- developer experience: good fit; one framework and one local database reduce setup friction
+- fit for the current project phase: strong fit; it supports learning and iteration without scale-driven design
+- lock-in risk: acceptable; Django shapes application structure, but the early-stage trade is reasonable given the simplicity benefits
+
+Trade-offs accepted with this decision:
+- Django is opinionated and less minimal than assembling only the exact pieces needed
+- SQLite is not a final answer for every future production scenario
+- skipping baseline containerization reduces parity with some future deployment approaches, but keeps local workflow simpler now
+
+## Consequences
+
+Future implementation work should assume:
+- Python as the default language
+- Django as the default application framework direction
+- SQLite as the initial persistence direction unless a later decision requires otherwise
+- local development should work without requiring containers
+
+This does not lock the project into a final production topology. It establishes the minimum stack direction needed for implementation to begin consistently.
+
+## Follow-Up Decisions Needed
+
+The following decisions are still expected later:
+- project layout and repository structure for the application code
+- testing tool and test execution details
+- production-grade database direction, if SQLite becomes insufficient
+- deployment/runtime topology
+- whether containers become useful later for packaging or deployment workflows