Merge branch 'feature/phase-1-containerized-postgres-baseline' 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 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.
+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
 
@@ -23,6 +23,14 @@ This document should stay aligned with the ADR set in `docs/adr/`. ADRs capture
 The current baseline decision is:
 - `ADR-0001`: runtime and development stack 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 Sections Placeholder
 
 Future versions of this document may include sections such as:

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

@@ -20,57 +20,78 @@ This decision covers:
 - whether containerization is part of the baseline developer workflow
 - acceptable operational complexity for the current stage
 
+This ADR is an intentional correction to the earlier baseline recorded in this same ADR. The previous non-containerized local workflow and SQLite baseline are rejected because they do not match the actual project requirement for containerized development with PostgreSQL as the default database direction.
+
 ## 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
+- persistence direction: PostgreSQL is the baseline database direction
-- containerization: not part of the baseline developer workflow in the current phase
+- containerization: development must happen in containers by default
-- operational complexity: keep it low; default to one application process and the simplest local setup that supports iteration
+- operational complexity: keep it low, but not at the expense of the required containerized workflow or the PostgreSQL baseline
 
-This baseline is intentionally conservative. It favors a familiar, batteries-included web framework and a minimal local setup over early complexity.
+Practical rule for future implementation work:
+
+- assume Python 3
+- assume Django
+- assume PostgreSQL
+- assume a containerized development workflow
+
+Containerized development is part of the baseline, not an optional convenience.
 
 ## Alternatives Considered
 
-### Option A: Python 3 + Django + SQLite + no baseline containerization
+### Option A: Python 3 + Django + PostgreSQL + required containerized development
 
 Chosen.
 
-### Option B: Python 3 + FastAPI + SQLAlchemy + PostgreSQL + optional containers
+This is the corrected baseline because it matches the actual project requirements and gives future implementation work one explicit, repeatable environment assumption.
 
-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 B: Python 3 + Django + PostgreSQL + optional or non-containerized development
 
-### Option C: JavaScript/TypeScript full-stack baseline with Node.js, a web framework, and a separate database
+Not chosen. This is explicitly rejected because development must be containerized. Allowing a non-containerized default would reintroduce machine-specific drift and contradict the project requirement.
 
-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.
+### Option C: Python 3 + Django + SQLite + required or optional containers
+
+Not chosen. SQLite is no longer the preferred baseline because the project requires PostgreSQL as the default persistence choice. Once containers are mandatory, the convenience advantage of SQLite is no longer enough to justify choosing a different database than the one future implementation should actually assume.
+
+### Option D: Python 3 + FastAPI + SQLAlchemy + PostgreSQL + required containerized development
+
+Not chosen. This remains a plausible stack in general, but it adds more assembly and more framework decisions than the current phase needs when Django already satisfies the baseline direction.
 
 ## Trade-Offs
 
 Evaluation against the standard decision criteria:
 
-- simplicity: strong fit; Django and SQLite keep the baseline small and reduce early setup choices
+- simplicity: acceptable; the required container workflow adds setup structure, but the baseline stays simple by standardizing one framework, one database, and one development path
-- portability: strong fit; Python and SQLite are workable across machines without assuming containers
+- portability: strong fit; containerized development reduces machine-specific drift and gives contributors a more consistent environment
-- maintainability: good fit; the baseline favors a conventional, well-documented structure over novelty
+- maintainability: good fit; Django and PostgreSQL are conventional, well-understood defaults with clear documentation paths
-- operational complexity: strong fit; no baseline container dependency and no multi-service assumption
+- operational complexity: moderate but acceptable; containers and PostgreSQL add more moving parts than SQLite, but that complexity is required and bounded
-- testability: good fit; Django provides established testing support for early implementation work
+- testability: good fit; the baseline supports realistic database-backed testing against the same database family future work will assume
-- developer experience: good fit; one framework and one local database reduce setup friction
+- developer experience: acceptable to good; containers add overhead, but they reduce local setup ambiguity once the workflow is documented
-- fit for the current project phase: strong fit; it supports learning and iteration without scale-driven design
+- fit for the current project phase: good fit; it is more structured than the earlier baseline, but it matches the actual requirement and avoids rework from an unrealistic database choice
-- lock-in risk: acceptable; Django shapes application structure, but the early-stage trade is reasonable given the simplicity benefits
+- lock-in risk: acceptable; Django shapes application structure and PostgreSQL becomes the assumed database family, but both are justified by the need for a stable, documented baseline
 
 Trade-offs accepted with this decision:
-- Django is opinionated and less minimal than assembling only the exact pieces needed
+- containerized development adds baseline workflow overhead compared with a purely local setup
-- SQLite is not a final answer for every future production scenario
+- PostgreSQL is heavier than SQLite for the smallest possible local start
-- skipping baseline containerization reduces parity with some future deployment approaches, but keeps local workflow simpler now
+- Django remains opinionated, but that is acceptable for a maintainable default direction
+
+Why the earlier baseline is rejected:
+- non-containerized development is not acceptable because the project requirement is explicit and future work must assume one standard workflow
+- SQLite is not acceptable as the default baseline because future implementation should target PostgreSQL directly rather than split early assumptions from later reality
 
 ## 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
+- PostgreSQL as the baseline persistence direction
-- local development should work without requiring containers
+- local development is expected to run through a containerized workflow by default
+
+This correction is required, not optional. Future implementation prompts should assume containers and PostgreSQL unless a later ADR explicitly supersedes this baseline.
 
 This does not lock the project into a final production topology. It establishes the minimum stack direction needed for implementation to begin consistently.
 
@@ -78,7 +99,12 @@ This does not lock the project into a final production topology. It establishes
 
 The following decisions are still expected later:
 - project layout and repository structure for the application code
+- container orchestration details for local development
+- Django and PostgreSQL service wiring details
 - 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
+
+Still undecided after this correction:
+- exact container tooling details and command structure
+- exact PostgreSQL version/policy
+- how local secrets and environment configuration will be managed inside the containerized workflow