From 1cdf7ac1d1db2897489c81224e6070fa68829111 Mon Sep 17 00:00:00 2001 From: bisco Date: Fri, 20 Mar 2026 19:37:44 +0100 Subject: [PATCH] docs: record baseline runtime stack decision --- docs/ARCHITECTURE.md | 5 +- .../adr/0001-runtime-and-development-stack.md | 84 +++++++++++++++++++ 2 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0001-runtime-and-development-stack.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index c8dd413..02cc0e1 100644 --- a/docs/ARCHITECTURE.md +++ b/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: diff --git a/docs/adr/0001-runtime-and-development-stack.md b/docs/adr/0001-runtime-and-development-stack.md new file mode 100644 index 0000000..37f8c7c --- /dev/null +++ b/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