clean-arch

README

Clean Architecture

This project demonstrates an example Go (Golang) realization of the Clean Architecture using the Gin Gonic web framework. The GORM library and a PostgreSQL DBMS are used for data persistence and podman based testing codes are provided too.

Four main layers are seen as depicted in the following component diagram. These layers are usually drawn as co-centered circles. The inner-most layer is the Entities layer which is also known as the Models or Domain layer. This layer contains the entity types which are defined in the business domain and may be used by a high-level implementation of interesting use cases, without technology-specific implementation details. These models are expected to have the least foreseeable changes since their changes are likely to propagate to other layers. As an example entity in this project, we can mention the model.Car type. These models may be used by both of the Use Cases and Adapters layers. The standard language libraries are treated similarly too.

The Use Cases or Use Case Interactors layer contains the core business logic of a system. This code may use the defined models for different purposes such as data passing, requests/responses formatting, or data persistence. This layer can be seen as a facade for the entire system too as it defines the acceptable public use cases of a system. The high-level implementation of this layer makes it relatively stable as it only depends on the domain entities and does not need to change whenever a third-party library is updated or when a new technology is supposed to be adapted. As an example type from this layer, take a look at the carsuc.UseCase type.

A concrete method is required in order to wire up the use cases of a system to the use cases of other systems, allowing them to interact based on their expected and exposed public interfaces. For example, a web framework such as Gin Gonic requires a series of HandlerFunc functions in order to call them when a web request is recevied which may be different from how they are managed in Echo. Conversely, use cases require to employ functionalities of an ORM like the GORM in order to store or search among models, having a database management system server. The Adapters layer which is also know as Controllers or Gateways is responsible to fill these gaps without making the frameworks and third-party libraries on one hand and the use case interactors on the other hand dependent on each other. The use cases layer contains repo.Cars example interface in order to show its expectations from a cars repository. This interface is realized by carsrp.Repo from the adapters layer, where it uses GORM and Pgx libraries for interaction with a PostgreSQL DBMS server. The adapters layer depends on both of our high-level logics and other libraries provided/required interfaces in order to adapt them together. To be precise, the Controllers is not a suitable alias for this layer because adapters should be thin and focus on converting interfaces or simple serialization/deserialization tasks, while the use cases layer contains the more complex business-level flow controls. Parsing configuration such as config.Config and instantiating components from other layers during the system startup are also a part of this layer.

The outmost layer contains Frameworks and Libraries which are usually implemented independent of the main project. Their codes are also independent of our system and may change from time to time, or we may need to replace them with alternatives as new technologies are introduced. Because it is desired to keep our codes immune to changes in the APIs of those libraries, adapters layer has to hide their details by realizing the use cases layers interfaces and implementing any missing functionality or mismatched expectations. Indeed, these frameworks are parallels to our use cases layer, but in their own project.

Read More

For further reading, you may check

• Martin, R. C., Grenning J., & Brown S. (2017). Clean architecture.
• Lano, K., & Yassipour Tehrani, S. (2023). Introduction to Clean Architecture Concepts. In Introduction to Software Architecture: Innovative Design using Clean Architecture and Model-Driven Engineering (pp. 35-49). Cham: Springer Nature Switzerland.