Screaming Architecture und Use-Case-Intention

Open a typical project and you often see folders named controllers, models, views. That structure shouts the framework, not the purpose.

Robert C. Martin called the alternative Screaming Architecture: the top-level structure should scream what the system does.

Just as a building plan screams library or hospital, a healthcare app should scream patient scheduling and billing — not Spring or React.

The use cases are the heart of the system, so they should be the most visible thing.

A framework-driven layout buries the domain.

A use-case-driven layout puts the domain first.

This reinforces a core Clean Architecture idea: the framework is a delivery mechanism, a detail you plug in.

Your business rules should not depend on whether you chose one web framework over another. The structure should make that independence obvious.

When the domain leads the structure, you can defer infrastructure choices.

You can begin building and even testing core use cases before committing to a database or web framework, because those live at the edges.

A telltale sign of screaming architecture: you can test all your use cases without the framework, the UI, or the database running.

If your tests need a web server to verify a business rule, the framework has leaked into the core.

Each major use case or feature becomes a clearly named module or package. Inside it live the entities and interactors that implement that capability.

Think of the web, the database, and external services as plugins to your application core.

The core defines the rules; the plugins adapt the outside world to those rules. This mindset directly produces screaming structure.

Teams sometimes resist because frameworks ship with conventional folder layouts.

You can still honor those conventions at the edges while organizing your core by domain. The goal is that the most important code is the most visible.

• Can a newcomer guess what the app does from the folder names?
• Can you delay choosing a database?
• Can use cases be tested without the framework?

Three yeses mean your architecture is screaming the right thing.

You learned that a clean structure should scream its domain.

• Organize by use case, not by framework role.
• Frameworks and databases are deferrable details.
• If use cases test without the framework, intent leads the design.