Nothing is “wrong” in clean architecture. It doesn’t matter whether you have anaemic or rich domain models. All the entities need to do is to capture the high-level business rules.

2.) Use cases

Entities enforce high-level business rules. From a single responsibility perspective, they have only one reason to change. In fact.. They will probably not change at all. A mile will always be 5280 feet and we can only fit as many people in to a car as there are seats. That will never change.

But some things do change. When will a company bring a car to the junkyard? After 300,000 miles? After 5 years? A company is free to change that policy whenever they want. Those kind of business-rules are use-case specific. To not violate the Single Responsibility Principle, these “ifs” go into a separate file: the use-cases.

Use cases interact with the entities. They drive entities to achieve a business goal. Every use-case tells a story. And it might look like this:

Crossing the boundaries

The rule of clean architecture is: all dependencies point inwards. The entities are at the core of the application, the are use-case layer depends on the entities, and the infrastructure layer depends on the use-cases.

As you can see in the sample-code, the use-case layer interacts with infrastructure too. Like the database, for example. That makes the use-case layer seem dependent on the infrastructure layer. But with Clean Architecture, it should be the other way around. So how does that work?

At the core of the application, you’ll find entities, use-cases, and interfaces. These interfaces define what the outside layers will look like and how the use-cases will interact with it. But the implementation is not at the “core” of the application. It’s implemented in another layer. That’s how the boundary is crossed.

There are two types of interaction with use-cases. The use-cases interact with the system, or a system interacts with the use-cases. In ports-and-adapters, these are called the primary- and the secondary ports.

A primary port is an interface to something the application will respond to. Like a keyboard, for example. When you hit enter, the application will do something.

A secondary port is an interface to a system the application interacts with. Like a database. The application is operating the database. It sends it instructions, and the database responds to it.

Screaming architecture

In most of the applications I’ve worked with, this is what the folder structure looks like:

We have a tendency to group things by type. But this makes it unclear what the application does with these types. Not to mention it’s failing capacity to scale. Try putting 300 entities in a folder. It will be a mess.

Instead, focus on the functionality of the application. We are building a cab dispatching application. So, group everything by functionality, and have the application screaming “CABS!!! CAB DRIVERS!! I’M A CAB DISPATCHING APPLICATION!!!”. It should be clear what the application does by it’s file- and folder structure only, without reading a single line of code. Put interfaces, entities, and use-cases in the same folder. By grouping by functionality, the application will grow organically and remain easy to navigate:

Read more on Screaming Architecture here, and here.

3.) Controllers

The use cases and the entities are the core of the application. By invoking one, or a sequence of use cases, an application can achieve a business goal. There are several “things” that can do this. In case of an event-driven application, a command handler will typically invoke the use-cases. In my case, I’m building a REST API, and the consumer of the API can invoke the use-cases directly. A simple controller will look like this:

Note that I’m not using dependency injection on the constructor to inject the use-cases into the controller. I’m injecting directly into the method instead, because every controller method will probably use another use-case.

4.) Infrastructure

With the entities, use-cases, and controllers in place, there’s only one more layer left: The infrastructure layer. This layer contains things like database adapters, or API calls to third party API’s.

Implementing infrastructure on the outer layer has several advantages:

• They are easily replaceable. Nothing depends on it.
• The application becomes very testable. By mocking the infrastructure, all that’s left are the business rules.

4.2) Other infrastructure

Clean architecture projects often have a “Infrastructure” folder. This folder contains the adapters to the bits of infrastructure the application uses to accomplish things:

This application uses:

• Google maps to calculate distance and to find the nearest airport
• The imaginary JunkyardAndCo webservice to sell cars
• SqlServer to store the state of the entities
• Western Union to handle financial transactions

Putting it all together