hoopscout-v2/docs/adr/0002-initial-project-structure.md

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:

.
|-- 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