What does 'screaming architecture' (a term popularized by Robert C. Martin) mean, and how does choosing package-by-feature over package-by-layer support it?

## The diagnostic test Screaming architecture is the name Robert C. Martin gave, in a blog post later folded into his 'Clean Architecture' writing, to a simple diagnostic test: look at the top-level directory structure of a codebase and ask what it 'screams' at you before you've read a single line of code. His claim was that most codebases fail this test badly — they scream 'Ruby on Rails', 'Spring MVC', or 'this uses a repository pattern' rather than screaming 'this is a hospital patient-management system' or 'this is a payroll engine'. The architecture, in other words, is telegraphing the delivery mechanism and framework choices rather than the reason the software exists. ## Why layer names fail it The mechanism by which package-by-layer causes this failure is direct: when the top-level packages are named `controllers`, `services`, `repositories`, `dtos`, those names are vocabulary borrowed from the MVC/three-tier pattern itself, not from the business domain. - You could rename every business concept in the system — swap 'orders' for 'reservations', swap an e-commerce app for a hotel-booking app — and the top-level folder names wouldn't change at all, because they describe the technical skeleton, not the content poured into it. - That's the tell: architecture that scores badly on the screaming-architecture test looks the same across unrelated businesses. ## How package-by-feature fixes it Package-by-feature fixes this by construction, because the packaging decision is 'group by what the code is for' rather than 'group by what kind of class it is'. The top level becomes `orders`, `catalog`, `shipping`, `payments`, `users` — a table of contents that is specific to this business and would look completely different for a different business, because it's derived from the domain rather than the framework. ## Structure as documentation that cannot go stale Why does this matter beyond aesthetics or tidiness? Martin's underlying argument is about **intent-revealing structure** as a form of documentation that can't go stale, because it's the actual code layout, not a diagram in a wiki that nobody updates. A new engineer, or an outside auditor, or even a non-technical stakeholder skimming a repo listing, gets an immediate, accurate sense of what capabilities the system has just from folder names — 'oh, there's a shipping module and a payments module, but no returns module yet' is a real, load-bearing piece of information you can extract in ten seconds from a feature-packaged repo, and effectively impossible to extract from a layer-packaged one without reading service class names inside `services/` one by one. ## Speaking the vocabulary the business speaks There's a second, more practical payoff: alignment with how the business talks about the product. A product manager says 'shipping is broken for international orders': - In a **feature-packaged** codebase, an engineer's first move is literally 'open the shipping package', no translation step required. - In a **layer-packaged** codebase, the engineer first has to know, or search for, which specific classes across `controllers/`, `services/`, and `repositories/` implement shipping, because there is no single artifact in the file tree that corresponds to 'shipping' as a concept. ## The honest limitation The honest limitation is that screaming architecture is a heuristic about **legibility**, not a guarantee of good design. It's entirely possible to have feature packages that scream the domain correctly at the top level while being an unmaintainable mess inside — god classes, no separation of concerns, tangled cross-feature calls — because the test only inspects the top-level names, not what's inside each package or how packages depend on each other. Conversely, a disciplined team can run package-by-layer and still keep good internal quality; screaming architecture is about discoverability and communication, not a substitute for cohesion, low coupling, or good encapsulation, which have to be pursued separately (and which package-by-feature happens to make easier to enforce, but doesn't guarantee). ## Two repository listings, same framework A concrete, widely-cited illustration is Martin's own comparison of two hypothetical repository listings for a same-sized system: one where the root contains generic framework-standard folders and tells you nothing about the business, versus one where the root contains `Orders`, `Shipping`, `Billing` and immediately tells you this is a fulfillment system — even though both could be built with the exact same framework underneath. The framework is an implementation detail that should be swappable without renaming the business-facing structure; screaming architecture is the test for whether that's actually true of a given codebase.