Robert C. Martin's phrase 'screaming architecture' argues that a codebase's top-level structure should scream something specific about the system. What should it scream, and what's an example of an architecture that screams the wrong thing?
answer
- blueprint tells you it's a hospital, not the plumbing brand
- folder names should say what, not how
- controllers/services/models says nothing about the business
- group by use case/capability first
basics
~10 sThe top-level folders should announce what the app DOES (its use cases/domain), like 'Shipping' or 'PatientIntake' - not what framework it's built with, like 'controllers/models/views.'
solid answer
~50 sScreaming architecture is the idea that looking at a system's top-level directory structure should tell you what the system is for, before it tells you what it's built with. A Rails or generic MVC app whose top folders are controllers/, models/, views/, services/ screams 'I am a web app built with framework X' - you cannot tell from that layout whether it's a hospital system, an accounting system, or a game. A use-case-oriented layout instead groups by business capability first - folders like PlaceOrder/, CancelSubscription/, PatientIntake/ - each containing its own entities, interactors, and adapters, so the directory tree itself communicates the business intent. The framework and delivery mechanism (web vs CLI vs message queue) become a late, swappable detail rather than the organizing principle, reinforcing that architecture should be about intent, not about which web framework happens to be plugged in this decade.
go deeper
Can restate the core claim: top-level structure should reveal what the app does, not what framework it uses.
Can give a before/after example contrasting a framework-first layout with a use-case-first layout for a concrete domain.
Can identify 'cosmetic-only' adoption - renamed folders with unchanged structure underneath - as not satisfying the actual intent.
Can judge, for a specific existing codebase, whether the migration cost of reorganizing to a use-case-first structure is justified by the navigation/onboarding benefit.
## What the phrase means 'Screaming architecture' is a term Robert C. Martin coined by analogy to how you can tell a building's purpose from its blueprint before you know anything about its plumbing or wiring - a hospital blueprint screams 'hospital' via the layout of operating rooms, wards, and reception, not via which brand of pipe was used. Applied to software, the claim is that a system's top-level source structure - the first thing a new engineer sees when they open the repository - should scream what the system does for its users, i.e., its use cases and business capabilities, rather than screaming which web framework, ORM, or delivery mechanism it happens to use. ## The layout that screams the wrong thing A very common structure, especially in frameworks that generate scaffolding (classic Rails apps, many Spring Boot tutorials, generic N-layer templates), organizes top-level folders by technical role: `controllers/`, `services/`, `models/`, `repositories/`, `views/`. Opening that tree tells you almost nothing about the actual business - it could be a hospital system, a bookstore, or a game; every one of those apps could have the exact same folder names. Martin's complaint is that this layout answers the wrong first question. The framework is a delivery detail - one of the outermost, most replaceable rings in Clean Architecture - and organizing the whole codebase around it inverts the intended priority, making the volatile, low-value detail the most prominent thing about the system. ## The layout that screams the business A screaming layout instead groups code by business capability or use case first, and technical role second (or not visible at the top level at all): folders like `PlaceOrder/`, `CancelSubscription/`, `PatientIntake/`, `ProcessPayroll/`, each self-contained, holding its own entities, interactors, and any adapters it needs. Within `PlaceOrder/` you might still have a controller and a gateway implementation, but they're nested under the capability, not promoted above it. Someone unfamiliar with the codebase can open the top-level directory and get a rough map of what the business does, purely from folder names, before reading a line of code or learning that the app happens to be built with Spring and Postgres this year. | Grouping | Top-level folders | What the tree communicates | |---|---|---| | Framework-first | `controllers/`, `services/`, `models/`, `repositories/` | the technical role of each folder | | Use-case-first | `PlaceOrder/`, `CancelSubscription/`, `PatientIntake/` | the business capability, purely from folder names | ## Why it follows from the Dependency Rule This isn't purely cosmetic - it's a consequence of taking the Dependency Rule seriously. If use cases genuinely don't depend on the framework, then grouping by framework artifact type is grouping by something the architecture itself says is a low-priority, swappable detail; grouping by use case groups by the thing the architecture says is central and stable. Screaming architecture is also meant as a forcing function: if you try to organize your code by use case and find you can't, because your 'use case' is actually three tangled technical concerns, that's a signal the design hasn't actually separated business rules from delivery mechanism yet, even if a Controllers/Services/Models split makes it look tidy. ## The cost, and the halfway failure - **The main cost.** Use-case-first structure is less familiar to engineers trained on framework conventions, so IDE tooling, generators, and 'where do I put a new repository' muscle memory built around controllers/services/models don't map cleanly, and some navigation (e.g., 'show me every controller') gets harder because controllers are scattered across use-case folders instead of colocated. - **The failure mode.** In practice it is doing this halfway: renaming top folders to sound like use cases (`OrderManagement/`) while the actual code inside is still one giant `OrderManagement/Controller.java`, `OrderManagement/Service.java`, `OrderManagement/Repository.java` split - the vocabulary screams business intent but the structure underneath is unchanged framework-first thinking, so the exercise produces cosmetic renaming without the underlying decoupling or testability benefit. ## A worked example A hospital patient-intake system organized around screaming architecture might have top-level folders `PatientRegistration/`, `InsuranceVerification/`, `AppointmentScheduling/`, `BillingInquiry/` - each containing its own use-case class, entity references, and thin adapters - rather than `controllers/`, `services/`, `dao/`. A new engineer, or an auditor reviewing the system for compliance, can immediately see the shape of what the hospital does with patient data by scanning the top level, and can trace exactly one capability (say, `InsuranceVerification`) end to end without wading through unrelated billing or scheduling code mixed into a shared `services/` folder.
- Does adopting screaming architecture mean you can't have a controllers/ folder anywhere in the codebase?No - controllers still exist, they're just nested inside each use-case/capability folder (e.g. PlaceOrder/PlaceOrderController.kt) rather than promoted to a top-level folder that groups every controller in the system together regardless of what business capability it serves.
- What's a legitimate reason a team might keep a framework-first (controllers/services/models) layout despite this critique?Familiarity and tooling: many frameworks, generators, and new hires expect that convention, and for a small, simple CRUD app where every capability touches the same handful of models, the business-capability grouping may add navigation overhead without much payoff, since there isn't much business complexity to reveal.
- How would you tell, by looking at a repository's top-level folders alone, whether it follows screaming architecture?Check whether the folder names describe things a non-technical stakeholder would recognize as business capabilities (e.g. 'PatientIntake', 'InsuranceVerification') versus generic technical roles that would be identical across almost any web app (e.g. 'controllers', 'services', 'utils').
Like reading a building's floor plan: a hospital's floor plan screams 'hospital' through operating rooms, wards, and a reception desk, long before you learn which brand of pipe or wiring was used. A code structure should scream its business the same way, before it reveals which web framework wired it together.
saying these in an interview costs you the question
- thinks screaming architecture is about naming conventions/casing rather than what folders reveal about the business
- can't give an example of a 'framework-first' layout to contrast against
- believes renaming controllers/services/models folders to sound like use cases, with no structural change underneath, fully satisfies the idea
- conflates screaming architecture with logging or error messages ('screaming' as in loud output)