diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index a687735..44344cd 100644 --- a/docs/ARCHITECTURE.md +++ b/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: diff --git a/docs/adr/0002-initial-project-structure.md b/docs/adr/0002-initial-project-structure.md new file mode 100644 index 0000000..9198e7d --- /dev/null +++ b/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