docs: record configuration baseline

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