From 6e5c5f125846b74e0d7a4e1a42f2fedcbfc5435d Mon Sep 17 00:00:00 2001 From: bisco Date: Fri, 20 Mar 2026 19:56:10 +0100 Subject: [PATCH] docs: record containerized developer workflow --- docs/ARCHITECTURE.md | 3 + .../0003-containerized-developer-workflow.md | 96 +++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 docs/adr/0003-containerized-developer-workflow.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 44344cd..9942afe 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -23,6 +23,7 @@ This document should stay aligned with the ADR set in `docs/adr/`. ADRs capture The current baseline decision is: - `ADR-0001`: runtime and development stack baseline - `ADR-0002`: initial project structure baseline +- `ADR-0003`: containerized developer workflow baseline The current baseline assumes: - Python 3 @@ -34,6 +35,8 @@ Future implementation work should assume the containerized workflow and PostgreS Future scaffolding and implementation work should also follow the initial repository structure defined in `docs/adr/0002-initial-project-structure.md` unless a later ADR supersedes it. +Future runtime and scaffolding work should also follow the developer workflow defined in `docs/adr/0003-containerized-developer-workflow.md`, including app and PostgreSQL containers as the baseline local services and container-run development commands by default. + ## Future Sections Placeholder Future versions of this document may include sections such as: diff --git a/docs/adr/0003-containerized-developer-workflow.md b/docs/adr/0003-containerized-developer-workflow.md new file mode 100644 index 0000000..421cfd9 --- /dev/null +++ b/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