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

docs/ARCHITECTURE.md

@@ -22,6 +22,9 @@ 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
+- `ADR-0004`: configuration and environment strategy baseline
 
 The current baseline assumes:
 - Python 3
@@ -31,6 +34,12 @@ The current baseline assumes:
 
 Future implementation work should assume the containerized workflow and PostgreSQL baseline rather than introducing non-containerized local setups or a different default database.
 
+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 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/0002-initial-project-structure.md

@@ -0,0 +1,101 @@
+# ADR-0002: Initial Project Structure
+
+- Status: accepted
+- Date: 2026-03-20
+
+## Context
+
+The repository now has a documented baseline runtime direction:
+- Python 3
+- Django
+- PostgreSQL
+- containerized development by default
+
+Before implementation starts, the project also needs one explicit repository and application structure decision. Future prompts should not guess where application code, infrastructure files, tests, or helper tooling belong.
+
+The initial structure must stay small, phase-appropriate, and easy to understand. It should support containerized development and Django implementation without introducing modularity or infrastructure complexity that the project has not yet earned.
+
+## Decision
+
+Use a single application repository with one initial Django application structure.
+
+Future implementation work should follow this high-level layout:
+
+```text
+.
+|-- app/                  # Django project and application code
+|-- tests/                # repository-level test suites as needed
+|-- infra/                # container and infrastructure-related files
+|-- docs/                 # repository and architecture documentation
+|-- scripts/              # helper scripts and developer tooling
+|-- Makefile
+|-- AGENTS.md
+`-- README.md
+```
+
+Interpretation rules for future work:
+- keep the repository as a single application repo for now
+- place Django project and application code under `app/`
+- place container and infrastructure files under `infra/`
+- keep documentation under `docs/`
+- keep helper scripts and local tooling under `scripts/`
+- place tests in `tests/` unless there is a clear, documented reason to colocate a specific test type later
+- optimize for one initial Django project/application structure, not immediate modular decomposition
+
+This structure is the default implementation baseline unless a later ADR supersedes it.
+
+## Alternatives Considered
+
+### Option A: Single repository, `app/` for Django code, `infra/` for container/infrastructure files, `tests/` for tests
+
+Chosen.
+
+This is the best fit for the current phase because it creates a clear, maintainable boundary between application code, infrastructure, documentation, and tooling without forcing early complexity.
+
+### Option B: Keep everything close to the repository root with minimal directory separation
+
+Not chosen. This would reduce early directory count, but it would blur boundaries between application code, infrastructure, and tooling once containerized development begins.
+
+### Option C: Start with a more modular or multi-package layout immediately
+
+Not chosen. This would over-design the repository before implementation has established real module boundaries or scaling needs.
+
+### Option D: Split application and infrastructure into multiple repositories
+
+Not chosen. This would add coordination overhead and reduce clarity at a stage where the project still benefits from one portable repository-owned workflow.
+
+## Trade-Offs
+
+- this structure is slightly more formal than the smallest possible root-only layout
+- using a top-level `tests/` directory favors clarity and broad test organization, but some future test colocations may still prove useful
+- choosing one initial Django project/application direction defers modularity decisions until real implementation pressure exists
+
+Why this is appropriate for the current phase:
+- it gives future implementation prompts a direct, shared structure to follow
+- it supports containerized development and PostgreSQL without mixing infrastructure files into application paths
+- it keeps the repository understandable across machines and contributors
+
+What is intentionally deferred:
+- detailed Django internal app decomposition
+- whether later code should be split into multiple Django apps or packages
+- exact container file names and orchestration details
+- advanced deployment layout decisions
+
+## Consequences
+
+Future scaffolding and implementation work should:
+- create Django code under `app/`
+- place container and infrastructure assets under `infra/`
+- keep docs in `docs/`
+- keep helper tooling in `scripts/`
+- add tests under `tests/` by default
+
+Future prompts should interpret this ADR as direct structure guidance, not a loose suggestion.
+
+## Follow-Up Decisions Needed
+
+The following decisions are still expected later:
+- exact Django project/package names under `app/`
+- exact test layout conventions inside `tests/`
+- exact container file names and orchestration commands under `infra/`
+- environment configuration and secrets handling for the containerized 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

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