# Screaming Architecture

> If you were to glance at the folder structure of your system, could you tell what the system is about? Your architecture should communicate what problems it solves. This approach is called screaming architecture.

Published: 2024-08-24. Author: Milan Jovanović.

Canonical: https://milanjovanovic.tech/blog/screaming-architecture

Screaming architecture means your folder structure tells a reader what the system does, not which framework it runs on.
You get there by making use cases and feature folders the top-level concept instead of `Controllers`, `Services`, and `Repositories`.
The payoff is higher cohesion and easier navigation.

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](https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html) 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:

```powershell
📁 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**](https://milanjovanovic.tech/blog/feature-folders-dotnet).
Inside a use case folder, we may find technical concepts required to implement it.

[**Vertical slice architecture**](https://milanjovanovic.tech/blog/vertical-slice-architecture) also approaches this from a similar perspective.

```powershell
📁 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](https://www.eventstorming.com/) 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**](https://milanjovanovic.tech/blog/bounded-context-ddd-explained).
This gives us loosely coupled high-level modules that we can translate into code.

![Bounded contexts.](https://milanjovanovic.tech/blogs/mnw_104/bounded_contexts.png)

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.
Bounded 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**](https://milanjovanovic.tech/blog/clean-architecture-folder-structure) internally.
But we can still organize the system around feature folders and use cases.
An alternative approach could be organizing around [**vertical slices**](https://milanjovanovic.tech/blog/vertical-slice-architecture-structuring-vertical-slices), resulting in a less nested folder structure.

```powershell
📁 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**](https://milanjovanovic.tech/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**](https://milanjovanovic.tech/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.

---

## Frequently asked questions

### What is screaming architecture?

Screaming architecture is a term coined by Robert Martin (Uncle Bob). It says a software system's structure should communicate what the system is about, so the folder structure screams the business domain (apartment booking, ticketing), not the framework it happens to use.

### What is a use case driven folder structure?

A use case represents a task a user wants to achieve, like reserving an apartment. A use case driven structure places use cases as the top-level concept, grouping related ones into feature folders, instead of technical folders like Controllers, Repositories, and Services.

### What are the benefits of screaming architecture?

Related use cases sit close together, so cohesion improves. You get high coupling within a single use case, low coupling between unrelated use cases, and easier navigation through the solution. It also aligns the codebase with the business domain.

### How does screaming architecture relate to vertical slice architecture and bounded contexts?

They are complementary. Vertical slice architecture organizes code from a similar use-case-driven perspective, while bounded contexts decompose the problem domain into loosely coupled high-level modules that translate into code. Screaming architecture is the idea of organizing for cohesion around functionality.

### Can you combine screaming architecture with Clean Architecture?

Yes. A module can use Clean Architecture internally, with Application, Domain, and Infrastructure layers, while still organizing the code inside each layer around feature folders and use cases such as SubmitOrder or RefundPayment.