Merge branch 'feature/phase-1-configuration-baseline' into develop

docs/ARCHITECTURE.md

@@ -24,6 +24,7 @@ The current baseline decision is:
 - `ADR-0001`: runtime and development stack baseline
 - `ADR-0002`: initial project structure baseline
 - `ADR-0003`: containerized developer workflow baseline
+- `ADR-0004`: configuration and environment strategy baseline
 
 The current baseline assumes:
 - Python 3
@@ -37,6 +38,8 @@ Future scaffolding and implementation work should also follow the initial reposi
 
 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 scaffolding should also follow the configuration strategy defined in `docs/adr/0004-configuration-and-environment-strategy.md`, including environment-variable based configuration, a repository-owned `.env.example`, local-only secrets, and a simple initial Django settings approach unless a later ADR supersedes it.
+
 ## Future Sections Placeholder
 
 Future versions of this document may include sections such as:

docs/adr/0004-configuration-and-environment-strategy.md

@@ -0,0 +1,98 @@
+# ADR-0004: Configuration and Environment Strategy
+
+- Status: accepted
+- Date: 2026-03-20
+
+## Context
+
+The project has already accepted these baseline decisions:
+- Python 3
+- Django
+- PostgreSQL
+- containerized development by default
+- a Docker Compose style developer workflow
+
+Before implementation starts, the repository needs one explicit configuration strategy so future prompts do not guess how environment-specific values, secrets, or Django settings should be handled.
+
+The baseline must stay simple, portable, and easy to understand across machines. It should work cleanly with containerized development without introducing a complex configuration framework before the application exists.
+
+## Decision
+
+Use environment variables as the baseline mechanism for runtime and application configuration.
+
+The baseline strategy is:
+- keep a versioned `.env.example` file in the repository
+- never commit real secrets, local-only credentials, or machine-specific private values
+- use local-only env files or equivalent local secret sources for actual sensitive values
+- have container orchestration provide environment variables through env files, direct environment variable definitions, or both
+- keep the initial Django configuration readable with one baseline settings module rather than a split-settings package by default
+
+Future implementation prompts should assume:
+- application/runtime configuration enters the app container through environment variables
+- `.env.example` documents the expected variable names and non-secret examples
+- local-only secrets stay out of git
+- container orchestration is responsible for wiring config into containers
+- Django settings should remain understandable and maintainable before any more advanced settings split is justified
+
+## Alternatives Considered
+
+### Option A: Environment-variable baseline with a committed `.env.example`, local-only secret files, and a simple initial Django settings module
+
+Chosen.
+
+This is the best fit for the current phase because it is portable, familiar, and easy to document without adding unnecessary configuration layers.
+
+### Option B: Commit more concrete local config files with real environment-specific values
+
+Not chosen. This would create unnecessary risk and conflict with the requirement that secrets and machine-specific values stay local.
+
+### Option C: Adopt a more elaborate split-settings or multi-layer configuration framework immediately
+
+Not chosen. This would add complexity before the project has enough implementation pressure to justify it.
+
+### Option D: Rely primarily on host-local configuration outside the container workflow
+
+Not chosen. This would weaken the clarity and portability of the mandatory containerized development baseline.
+
+## Trade-Offs
+
+- environment variables keep the baseline simple, but they require careful documentation of expected names and meanings
+- using `.env.example` improves onboarding clarity, but future work must ensure example values stay non-sensitive
+- keeping one initial Django settings module is easier to understand early on, but future settings growth may eventually justify a more structured split
+
+What is expected to live in git:
+- `.env.example`
+- documented variable names and non-secret defaults/examples
+- configuration documentation
+- application settings code that reads from environment variables
+
+What must stay local:
+- real secrets
+- real local credentials
+- developer-specific overrides that should not be shared
+- machine-specific private paths or values
+
+How developers should expect configuration to enter containers:
+- through the container orchestration layer
+- using env files, direct environment variable definitions, or both
+- without requiring host-installed Python configuration as the normal workflow
+
+## Consequences
+
+Future implementation tasks should:
+- define configuration through environment variables
+- add a repository-owned `.env.example`
+- keep real secrets out of git
+- wire application containers to read configuration from container-supplied environment variables
+- keep the first Django settings layout simple and understandable
+
+Future scaffolding should follow this configuration strategy unless a later ADR supersedes it.
+
+## Follow-Up Decisions Needed
+
+The following decisions are still expected later:
+- exact initial variable names and documented defaults
+- exact env file names and placement for local development
+- whether any non-secret shared defaults should live in orchestration files directly
+- whether and when Django settings should be split into multiple modules
+- how production and non-development secret delivery will work later