hoopscout-v2/docs/adr/0003-containerized-developer-workflow.md

ADR-0003: Containerized Developer Workflow

• Status: accepted
• Date: 2026-03-20

Context

The project has already accepted these baseline decisions:

• Python 3
• Django
• PostgreSQL
• containerized development by default
• a single application repository with application code under app/ and infrastructure assets under infra/

Before implementation starts, the repository needs one explicit developer-workflow decision so future tasks do not guess how local commands, services, or persistence should work. The workflow must be portable across machines, low-ambiguity, and small enough for the current phase.

Decision

Use a Docker Compose style workflow, or an equivalent container orchestration approach with the same behavior, as the baseline developer workflow.

The baseline developer workflow must include at least:

• one application container for Django development work
• one PostgreSQL container for the baseline database service

The baseline workflow also assumes:

• application source code is mounted into the app container during development
• routine development commands run through containers by default
• persistent local development database data is handled through a container-managed persistent volume or equivalent durable container storage
• host-installed Python is optional and unsupported for normal development workflow

Minimum required developer experience:

• a contributor can start the baseline services through the containerized workflow
• application commands run inside the app container
• the application talks to PostgreSQL through the containerized environment
• the workflow behaves consistently across machines without depending on undocumented local Python setup

Future implementation tasks should treat this as direct workflow guidance, not as an optional convenience.

Alternatives Considered

Option A: Docker Compose style baseline with one app container, one PostgreSQL container, mounted source, and container-run commands

Chosen.

This is the best fit for the current phase because it gives the project one clear, repeatable development path while keeping the service set intentionally small.

Option B: Containerized database, but application commands run on the host machine

Not chosen. This would keep too much variation in local Python setup and weaken the portability goal of mandatory containerized development.

Option C: Fully local host-based development with optional containers

Not chosen. This conflicts with the already accepted runtime baseline and would reintroduce machine-specific ambiguity.

Option D: More production-like multi-service developer orchestration from the start

Not chosen. This would add complexity the project has not yet earned and is not required for the current phase.

Trade-Offs

• this workflow adds container orchestration overhead compared with purely local commands
• mounted source inside the app container improves iteration speed, but requires clear volume and command conventions later
• persistent database data in container-managed storage is more realistic than ephemeral local-only setup, but requires explicit reset/cleanup decisions later

Why this is the best fit for the current phase:

• it matches the already accepted requirement for containerized development
• it keeps the developer baseline limited to the minimum useful services
• it improves portability across machines by standardizing how development commands run
• it avoids premature production-grade complexity

What is intentionally deferred:

• exact Compose file names or orchestration command names
• exact image build details
• reverse proxy or extra service containers
• production deployment orchestration
• detailed data reset and backup workflows for local development

Consequences

Future implementation tasks should assume:

• local development commands run through containers by default
• the app service and PostgreSQL service both exist in the developer baseline
• source code is mounted into the app container during development
• database persistence is handled by container-managed durable local storage
• host-installed Python should not be the normal path for project development

Future runtime and scaffolding work should follow this workflow unless a later ADR supersedes it.

Follow-Up Decisions Needed

The following decisions are still expected later:

• exact orchestration file names and locations under infra/
• exact command entrypoints for common development tasks
• environment variable and secrets handling for the containerized workflow
• local data reset and cleanup conventions
• whether any additional developer services are needed beyond app and PostgreSQL