Oh My Learning

Screaming Architecture and Test Boundaries

clean-architecture/13 mid drafted · 8 min read

Clean Architecture (Robert C. Martin), Chapters 21, 28

Prerequisites clean-architecture/08

Screaming Architecture and Test Boundaries#

TL;DR#

Looking at a well-architected system's top-level structure should immediately tell you what business the system is for — a health-record system's top-level folders should scream "this is a health-record system," not "this is a Rails app" or "this is a Spring Boot app." Tests, meanwhile, should be treated as a genuine architectural boundary in their own right — coupled tightly enough to verify real behavior, but never coupled to volatile implementation details that would make the test suite itself fragile against routine refactoring.

The idea#

This closing lesson bundles two related, practical consequences of everything established earlier in this subject: screaming architecture is a diagnostic test you can apply just by looking at a project's folder structure, checking whether the Dependency Rule (clean-architecture/08) has actually succeeded in keeping frameworks and delivery mechanisms out of the system's most prominent, top-level organization. Test boundaries apply the same dependency-rule thinking specifically to the test suite itself, which this subject's earlier lessons haven't yet directly addressed as its own architectural concern.

How it works#

Screaming architecture — what your top-level folders say about your system#

Martin's test: if you look at a project's top-level directory structure — before reading a single line of business logic — what does it tell you? If the answer is "this is a Django app" or "this is a React app" (organized by controllers/, models/, views/, or by framework convention), the architecture is screaming the wrong thing — it's telling you about a delivery mechanism and framework choice, which per clean-architecture/11 are supposed to be mere details, not the system's defining organizational feature. A well-architected system's top-level structure should instead scream the business it's for: folders like loans/, underwriting/, payments/, patient_records/ — organized around Use Cases and business capabilities, with the specific framework and delivery mechanism relegated to a clearly-labeled, subordinate detail (perhaps a web/ or infrastructure/ folder, present but not architecturally prominent).

Worked example — before and after.

# Before — screams "this is a Django app," not "this is a lending business"
myapp/
  models.py
  views.py
  serializers.py
  urls.py

# After — screams the actual business the system serves
loans/
  entities.py         # Loan, Payment (Entities)
  use_cases.py         # SubmitLoanApplication, ApproveLoan (Use Cases)
  gateways.py           # OrderRepository interface, etc.
web/                   # the framework detail, clearly subordinate
  views.py
  urls.py

This directly operationalizes clean-architecture/01's point about architecture's purpose and clean-architecture/11's "the web is a detail" argument into a simple, checkable, at-a-glance test anyone (including a new hire, or a business stakeholder skimming the repo) can apply without reading a single line of actual logic.

Why this test matters as a diagnostic, not just an aesthetic preference#

The screaming-architecture test is valuable specifically because it's a fast, cheap proxy for whether the Dependency Rule has actually been followed in practice, throughout the whole codebase — if the top-level structure is organized around a framework's conventions, that's strong circumstantial evidence the business logic is also organized around (and likely coupled to) that framework internally, even before you've inspected any actual import statements. Conversely, a top-level structure organized around business capability is at least consistent with (though not, by itself, proof of) a codebase that has genuinely kept its business logic independent.

Tests as their own architectural boundary#

A distinct, closing point: the test suite itself is a client of the production code, sitting at its own boundary — and like any client-boundary relationship, tests should depend on production code's stable interfaces, not on its volatile internal details. A test suite tightly coupled to production code's internal implementation (testing private methods directly, asserting on internal data structures rather than observable behavior — exactly refactoring/03's caution about tests that "work against refactoring") becomes fragile: every internal refactoring, even a genuinely behavior-preserving one, breaks tests that were never supposed to care about how the behavior was achieved, only that it was achieved correctly.

The specific architectural implication. Structuring tests to depend on the same stable interfaces (Use Cases, Entity public methods) that the rest of the system depends on — rather than reaching into implementation details — means tests benefit from the exact same Dependency Rule discipline as the rest of the architecture: they depend inward, on stable abstractions, and are correspondingly insulated from outward, volatile changes (which framework is used to run the tests, which specific mocking library, which specific database is used for integration tests).

Worked example.

# Fragile — test depends on internal implementation detail
def test_loan_approval():
    loan = Loan(...)
    loan._internal_risk_score = 0.3   # reaching into a private field directly
    assert loan.approve() == True

# Robust — test depends only on the stable, public interface
def test_loan_approval():
    use_case = ApproveLoanUseCase(risk_service=FakeRiskService(score=0.3))
    result = use_case.execute(loan_application)
    assert result.approved == True

The robust version depends on ApproveLoanUseCase's stable public interface and a properly-substituted fake dependency (echoing legacy-code/05's dependency-breaking techniques) — a future internal refactoring of exactly how risk scoring is computed or stored internally won't break this test, because the test never depended on that internal detail in the first place.

Pros#

  • Screaming architecture gives a fast, cheap, at-a-glance diagnostic for whether a codebase's Dependency Rule discipline is likely being followed, without needing to read every file.
  • Organizing top-level structure around business capability makes a codebase immediately legible to new team members and stakeholders in terms of what the system actually does, rather than requiring familiarity with a specific framework's conventions first.
  • Treating tests as their own dependency-rule-respecting boundary produces a test suite that survives routine refactoring, directly supporting refactoring/03's safety-net requirements rather than working against them.

Cons#

  • Restructuring an existing, framework-organized codebase to scream business capability instead is itself a substantial refactoring effort, not a quick fix — most real, existing codebases weren't built this way from the start.
  • Screaming architecture is a useful proxy, not a guarantee — a business-capability-organized top-level structure can still hide framework-coupled logic deeper inside, so the test should prompt further investigation, not be treated as conclusive proof on its own.
  • Applying full dependency-rule discipline to tests (never depending on internal details) can occasionally make certain white-box tests (deliberately checking specific internal states, per code-complete/13's structural-coverage discussion) harder to write — a real tension between test robustness and certain kinds of thorough, structure-aware test coverage.

Alternatives#

  • Framework-convention-organized codebases, accepting the coupling this lesson warns against — a reasonable, pragmatic choice for genuinely framework-centric applications with little enduring, framework-independent business logic to protect (echoing clean-architecture/09's cost/benefit test).
  • Domain-driven bounded-context-based organization (see domain-modeling/ddd-evans) — a closely related, often complementary way of organizing a codebase around business meaning, sometimes at a coarser grain (whole bounded contexts) than this lesson's "top-level folders scream the business" test.
  • Snapshot/golden-master testing (legacy-code/03) — a different testing strategy that, for some purposes, sidesteps the internal-detail-coupling risk entirely by asserting on large, holistic outputs rather than fine-grained internal state, at the cost of less precise failure diagnosis.

When to use it#

Apply the screaming-architecture test periodically as a quick health check on any codebase's top-level organization, and prioritize business-capability-based structure for any new project or major restructuring effort. Apply dependency-rule discipline to test design specifically for tests meant to survive routine internal refactoring (most unit and Use-Case-level tests).

When NOT to use it#

Don't force a full restructuring of an existing, working, framework-organized codebase purely to satisfy the screaming-architecture aesthetic, without a concrete, evidenced benefit driving the change (echoing refactoring/02's "refactor because it serves a real, upcoming need" guidance). Don't apply strict interface-only test dependency universally if a specific, deliberate white-box test genuinely needs to verify internal structural details as part of its actual purpose.

Key takeaways / mental model#

Look at your project's top-level folder structure and ask: "does this tell a stranger what business we're in, or does it just tell them which framework we picked?" And for any test, ask: "does this test depend on a stable, public interface, or does it reach into something that a legitimate, behavior-preserving refactoring could reasonably change?"

Self-check questions#

  1. Look at a real project's top-level folder structure (yours or one you know) and apply the screaming-architecture test. What does it currently scream, and what would you change to make it scream the business instead?
  2. Using the Loan test example, explain precisely why the fragile version breaks under a legitimate refactoring that the robust version survives.
  3. Why is screaming architecture described as a "useful proxy, not a guarantee"? What would you need to check beyond just the top-level folder names to be more confident the Dependency Rule is actually being followed?
  4. Describe a case where a white-box test genuinely needs to check internal structural details, and explain how you'd balance that need against this lesson's general preference for interface-only test dependencies.

References#

  • Clean Architecture: A Craftsman's Guide to Software Structure and Design (Robert C. Martin), Chapter 21: "Screaming Architecture" and Chapter 28: "The Test Boundary".