Merge branch 'feature/phase-1-project-structure-decision' into develop

docs/ARCHITECTURE.md

@@ -22,6 +22,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
 
 The current baseline assumes:
 - Python 3
@@ -31,6 +32,8 @@ 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 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