102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# 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
|