docs: record containerized developer workflow

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

@@ -0,0 +1,96 @@
+# 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