ADR-0009 - Directory name must match the discipline name #

• Status: Accepted
• Date: 2026-05-07
• Deciders: Natan
• Supersedes:
  • The directory naming in

ADR-0001 (Decision body references apps/; the three-layer split itself stands).

• The vocabulary in ADR-0008

(uses "app" throughout for what this ADR calls "system under test"; the general-purpose runner principle stands).

Context #

SQA stands for System Quality Assurance. The discipline-level noun is system. Yet the directory holding the per-system test flows was originally named src/apps/, with each system-under-test living at src/apps/<name>/.

This produced a vocabulary collision visible to every reader:

"SQA tests systems. Each system gets its own app."

Two words for the same concept. Worse, "app" carries layperson baggage that doesn't fit:

• A user-facing piece of software is colloquially "an app". The thing

under test (snappy-api) is such an app. So src/apps/snappy-api/ literally read as "the app that is the snappy-api app" - incoherent.

• At SQA's level of analysis, snappy-api isn't usefully called an

app - it's a system being verified, irrespective of its internal shape (it could be a service, a worker, a pipeline, or a third-party API).

We considered three options:

1. Rename apps/ → systems/. One word, five places (discipline,

directory, doc, env var, conversation). Honest about scope.

1. Keep apps/ and redefine "app" as "an SQA test flow." Zero

rename, but every reader has to learn a redefinition that contradicts the lay meaning. Drift-prone.

1. Rename SQA → AQA (Application Quality Assurance). Vocabulary

becomes consistent, but the word becomes false: SQA verifies network, storage, queues, schedulers, deploys, and business outcomes - none of which are "the application". Renaming SQA adopts a narrower-than-reality word. Rejected.

Decision #

The directory holding per-system test flows is named src/systems/.

The name of any container that scopes the discipline-level noun must match that noun. For SQA, the discipline-level noun is system, so every place a reader meets it - discipline name, directory name, doc file name, env var, conversation - uses the same word.

Concrete renames executed by this ADR:

Before	After
src/apps/	src/systems/
src/apps/snappy-api/	src/systems/snappy-api/
docs/guides/add-an-app.md	docs/guides/add-a-system.md
Future env var SQA_APP	SQA_SYSTEM

The function names (runSnappyApi) and the package name (@metaintro/sqa) keep their existing casing - they were already free of the collision.

Two senses of "system" - both intentional #

The word "system" now appears in two layout positions:

• src/components/<system>/ - the external system a component

talks to (S3, an HTTP endpoint, a queue, a database). One folder per external system probed.

• src/systems/<system>/ - the system under test. One folder per

discipline-level system holding the ordered flow that probes it.

A system under test is composed by reaching into many external-system components. The shared word is correct: at SQA's level of analysis, both are "systems we reason about." Where the distinction matters in prose, qualify it ("external system" vs "system under test"); the architecture explanation does this in its Vocabulary note ↗.

Consequences #

• Pro: One discipline-level word across discipline name,

directory name, env var, doc file name, and conversation. The reader learns "system" once and meets it everywhere.

• Pro: New contributors won't ask the question that prompted this

ADR ("if SQA is for systems, why is the folder called apps?").

• Pro: The principle - *the container that scopes the

discipline-level noun must be named for that noun* - is reusable. If a future tool's discipline-level noun shifts, the directory follows.

• Con: The same word now plays two roles in the layout

(components/<system>/ vs systems/<system>/). Mitigated by the Vocabulary note in docs/concepts/architecture.md and by the rule: if the role isn't obvious from context, qualify it ("external system" / "system under test").

• Con: Older ADRs (0001, 0008) still say "apps" in their bodies.

Per the supersede-don't-edit rule they stay as-is; this ADR carries the corrected vocabulary going forward.

• Falsifiability: Revisit if (a) the two senses of "system" cause

a real misread (someone puts code in the wrong layer because of the shared word), or (b) the discipline name changes such that "system" stops being the right word - at which point the directory changes, not the discipline.

See also #

• ADR-0001 - three-layer split

(Decision unchanged; this ADR renames one of the directories).

• ADR-0008 - SQA is general-purpose

(Decision unchanged; this ADR re-words "app" as "system under test").

• docs/concepts/architecture.md ↗ -

the Vocabulary note that distinguishes the two senses.

• README.md ↗ - narrative opener.