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

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: PostgreSQL is the baseline database direction
- containerization: development must happen in containers by default
- operational complexity: keep it low, but not at the expense of the required containerized workflow or the PostgreSQL baseline

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 + PostgreSQL + required containerized development

Chosen.

This is the corrected baseline because it matches the actual project requirements and gives future implementation work one explicit, repeatable environment assumption.

### Option B: Python 3 + Django + PostgreSQL + optional or non-containerized development

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.

### 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: 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; containerized development reduces machine-specific drift and gives contributors a more consistent environment
- maintainability: good fit; Django and PostgreSQL are conventional, well-understood defaults with clear documentation paths
- operational complexity: moderate but acceptable; containers and PostgreSQL add more moving parts than SQLite, but that complexity is required and bounded
- testability: good fit; the baseline supports realistic database-backed testing against the same database family future work will assume
- 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: 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 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:
- containerized development adds baseline workflow overhead compared with a purely local setup
- PostgreSQL is heavier than SQLite for the smallest possible local start
- 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
- PostgreSQL as the baseline persistence direction
- 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.

## Follow-Up Decisions Needed

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
- deployment/runtime topology

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