Screaming Architecture

If you were to glance at the folder structure of your system, could you tell what the system is about? And here's a more interesting question. Could a new developer on your team easily understand what the system does based on the folder structure?

Your architecture should communicate what problems it solves. Organizing your system around use cases leads to a structure aligned with the business domain. This approach is called screaming architecture.

Screaming architecture is a term coined by Robert Martin (Uncle Bob). He argues that a software system's structure should communicate what the system is about. He draws a parallel between looking at a blueprint for a building, where you can tell the purpose of the building based on the blueprint.

In this article, I want to show some practical examples and discuss the benefits of screaming architecture.

A Use Case Driven Approach

A use case represents a specific interaction or task that a user wants to achieve within your system. It encapsulates the business logic required to fulfill that task. A use case is a high-level description of a user's goal. For example, "reserving an apartment" or "purchasing a ticket". It focuses on the what of the system's behavior, not the how.

When you look at the folder structure and source code files of your system:

• Do they scream: Apartment Booking System or Ticketing System?

• Or do they scream ASP.NET Core?

Here's an example of a folder structure organized around technical concerns:

📁 Api/
|__ 📁 Controllers
|__ 📁 Entities
|__ 📁 Exceptions
|__ 📁 Repositories
|__ 📁 Services
    |__ #️⃣ ApartmentService.cs
    |__ #️⃣ BookingService.cs
    |__ ...
|__ 📁 Models

Somewhere inside these folders, we'll find concrete classes that contain the system's behavior. You'll notice that the cohesion with this folder structure is low.

How does screaming architecture help?

A use case driven approach will place the system's use cases as the top-level concept. I also like to group related use cases into a top-level feature folder. Inside a use case folder, we may find technical concepts required to implement it.

Vertical slice architecture also approaches this from a similar perspective.

📁 Api/
|__ 📁 Apartments
    |__ 📁 ReserveApartment
    |__ ...
|__ 📁 Bookings
    |__ 📁 CancelBooking
    |__ ...
|__ 📁 Payments
|__ 📁 Reviews
|__ 📁 Disputes
|__ 📁 Invoicing

The use case driven folder structure helps us better understand user needs and aligns development efforts with business goals.

Screaming Architecture Benefits

The benefits of organizing our system around use cases are:

• Improved cohesion since related use cases are close together

• High coupling for a single use case and its related use cases

• Low coupling between unrelated use cases

• Easier navigation through the solution

Bounded Contexts and Vertical Slices

We have many techniques for discovering the high-level modules within our system. For example, we could use event storming to explore the system's use cases. Domain exploration happens before we write a single line of code.

The next step is decomposing the larger problem domain into smaller sub-domains and later bounded contexts. This gives us loosely coupled high-level modules that we can translate into code.

The overarching idea here is thinking about cohesion around functionalities. We want to organize our system so that the cohesion between the components is high. Bonded contexts, vertical slices, and screaming architecture are complementary concepts.

Here's a screaming architecture example for this system. Let's say the Ticketing module uses Clean Architecture internally. But we can still organize the system around feature folders and use cases. An alternative approach could be organizing around vertical slices, resulting in a less nested folder structure.

📁 Modules/
|__ 📁 Attendance
    |__ ...
|__ 📁 Events
    |__ ...
|__ 📁 Ticketing
    |__ 📁 Application
        |__ 📁 Carts
            |__ 📁 AddItemToCart
            |__ 📁 ClearCart
            |__ 📁 GetCart
            |__ 📁 RemoveItemFromCart
        |__ 📁 Orders
            |__ 📁 SubmitOrder
            |__ 📁 CancelOrder
            |__ 📁 GetOrder
        |__ 📁 Payments
            |__ 📁 RefundPayment
        |__ ...
    |__ 📁 Domain
        |__ 📁 Customers
        |__ 📁 Orders
        |__ 📁 Payments
        |__ 📁 Tickets
        |__ ...
    |__ 📁 infrastructure
        |__ 📁 Authentication
        |__ 📁 Customers
        |__ 📁 Database
        |__ 📁 Orders
        |__ 📁 Payments
        |__ 📁 Tickets
        |__ ...
|__ 📁 Users
    |__ ...

The example above is a small part of the system I built inside of Modular Monolith Architecture.

Takeaway

Screaming Architecture isn't just a catchy phrase, it's an approach that can profoundly impact how you build software. By organizing your system around use cases, you align your codebase with the core business domain. Your system exists to solve the business domain problems.

Remember, the goal is to create a system that communicates its purpose through its structure. Embrace a use case-driven approach, break down complex domains into bounded contexts. Build a system that truly "screams" about the problems it solves.

If you want to explore these powerful ideas further, check out Pragmatic Clean Architecture. I share my entire framework for building robust applications from the ground up and organizing the system around use cases.

That's all for today.

See you next week.

---

P.S. Whenever you’re ready, there are 3 ways I can help you:

1. Pragmatic Clean Architecture: Join 3,000+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.

2. Modular Monolith Architecture: Join 850+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.

3. Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.