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

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