Clean Architecture is a way of writing code, organizing code introduced by Robert C. Martin. Let’s say that for you to understand, normally, when building a Java project to expose RESTful APIs, we will build a project with many different packages as follows:

Inside:

• The com.huongdanjava.cleanarchitecture.rest package will contain Controllers to handle requests from the user.
• The com.huongdanjava.cleanarchitecture.rest.dto package will contain Java classes to handle data from the user’s request and the data will be returned to the user.
• The com.huongdanjava.cleanarchitecture.service package will contain classes for handling business.
• The package com.huongdanjava.cleanarchitecture.db will contain the classes used for manipulating the database.
• The com.huongdanjava.cleanarchitecture.db.model package contains the model database table mapping with the Java class.
• The com.huongdanjava.cleanarchitecture.security package contains classes related to handling the security of the application.

All dependencies of the application will be declared in pom.xml file.

For small apps, organizing code like this shouldn’t be a big deal. But for large, multi-functional applications, imagine only a small change will need to change the code of the entire project. This will be very difficult to manage and if you are a novice to the project, it will be very difficult for you to understand what the application is doing and how it is coded.

Clean Architecture introduces a new way of writing code, organizing new code, ensuring the principle of separation of concerns when writing code, making it easy to add, extend, and remove features of the application without having to change a lot of code. Please see the image below:

Here is an overview of the concept of Clean Architecture.

The innermost layer is the Entities class (yellow), which is responsible for defining Java POJOs that contains the application’s business-related information. For example, if your application is about student information management, this class will contain a Java class that defines what student information includes?

The next layer outside the Entities layer is the Use Cases layer, (pink) which will contain the classes that define the business cases needed for the application. With the student management application above, the use cases that we can define in this layer are classes that allow us to add, delete, edit, and update student information.

One thing to note with the above two layers, Entities and Use Cases, is that we will not use any external library or framework, except for Use Cases layer, we may need to use Unit Testing related libraries.

In order for use cases to talk to external systems like database, web service, MQ server, we need a layer called Adapter layer (in green). Using Java, this Adapter layer contains interfaces for use by Use Cases layer. These interfaces will be implemented by the components in the outermost layer in the picture above (in blue color) depending on the needs of the application. In the student management application example, we can define interfaces to get student information from the database, update student information, …

There is a rule when writing Clean Architecture applications that, as you can see in the figure above where the arrow marks go from the outside, changes to the outer layer will not affect the code of the inside layer. The inner layers will not know what the code of the outer layers has.

To apply the concept of Clean Architecture, for Java applications, you can build a project with the Maven Module project and add an outer layer called Configuration that takes care of configuring how the application will run. Without this layer, the application cannot run.

Above are the basic ideas about Clean Architecture, in the following tutorial, I will go into practice how to implement a project using Clean Architecture.