Skip to content
SQA Cockpit

ADR-0008 - SQA is general-purpose, not Snappy-specific

ADRsUpdated 2 min readEdit on GitHub ↗

ADR-0008 - SQA is general-purpose, not Snappy-specific #

  • Status: Accepted (vocabulary widened by ADR-0009: "app" / src/apps/ is now "system under test" / src/systems/; the general-purpose runner principle is unchanged)
  • Date: 2026-05-07
  • Deciders: Natan
  • Supersedes: ADR-0001's Context

(only the framing - the three-layer decision itself stands)

Context #

ADR-0001 opens its Context with "the runner needs to verify multiple aspects of the Snappy stack across environments". That framing is too narrow: SQA is a general-purpose System Quality Assurance runner - operational verification for whichever software systems and business workflows we point it at. The Snappy API is the first system wired up (src/apps/snappy-api/), but more systems will follow as separate apps under src/apps/. ADR-0001's Decision (three layers: lib / components / apps) is already general - only the framing needs widening.

The README and docs/problem.md now state this scope explicitly. This ADR ratifies the same scope at the architectural level so future contributors don't infer Snappy-coupling from ADR-0001 alone.

Decision #

SQA is the runner. Apps under src/apps/ are the systems it tests.

  • The runner is generic. lib/ and components/ (and the

step() / log / formatter primitives) are written without reference to any one system.

  • Each app is one system. src/apps/<system-name>/ holds the

ordered, numbered flow that probes that system. The app is the Snappy/Conveyor/etc. boundary.

  • Components are reusable across apps. A new app reaches into

src/components/<system>/ for the capabilities it needs and only adds new ones for systems no other app has covered yet.

  • Adding a system = adding an app, never expanding the runner.

ADR-0001's three-layer split survives unchanged - this ADR only re-grounds its motivation in the general case. ADR-0007's operational-vs-experience scope continues to bound the kind of judgment every app makes.

Consequences #

  • Pro: New systems (e.g. Conveyor, Chat-Engine, Job-Matching) plug

in as src/apps/<system>/ without touching shared infrastructure.

  • Pro: Cross-system probes (e.g. is the same S3 bucket reachable

from two apps?) reuse one component, not two copies.

  • Pro: The README's narrative opener ("operational verification

for software systems and the business workflows running on them") matches the architecture, not just the aspiration.

  • Con: Naming a system as "the snappy app" rather than "the snappy

stack" is a small habit shift in conversation and PR titles.

  • Falsifiability: If an app starts importing private internals

from another app - or if a "system-agnostic" component starts branching on which app called it - the boundary has rotted and this ADR (or the layout) needs revisiting.

See also #

(Decision unchanged; this ADR widens its Context).

not audience-impression. Orthogonal: ADR-0008 names what SQA covers; ADR-0007 names how it judges.

What "SQA" means here section.

Was this page helpful?