Pragmatic Clean Code Architecture

The Entity Layer

[ part 1 | part 2]

In the previous post of the series, I’ve talked about The Use Case Layer of Clean Code Architecture. I’ve shown how we are structuring our business logic code and how it’s helping us keep the code that matters in a place that is decoupled from everything that goes around our applications and micro services. Give it a look, you will better understand how our Use Cases look like.

In this post I will talk about the Entity Layer and how we managed to create a balance between the theory and what is more practical for our everyday coding needs.

Image fromUncle Bob’sClean Code Arquitecture Blog Post — http://blog.8thlight.com/uncle-bob/2012/08/13/the-clean-architecture.htm

First things first. Uncle Bob’s Clean Code Architecture (CCA) tells us that an Entity is a representation of data of our domain, it’s so dumb that we are only giving the possibility to represent it self in a different way. No database access, nor business logic, only data.

In our apps Models are a key component so, migrating our Models to CCA Entities was, and still is, a really hard process. Also we use ActiveRecord a lot in our Models, which provides us with a straight forward ORM and some other goodies that we can’t just leave behind, at least for now. But we had to make some compromises and Pragmatic Entities are the result of those compromises.

Pragmatic Entities

For us, a Pragmatic Entity is still an ActiveRecord Model that is used to CRUD data from the database and represent it inside our business logic.

As I said before, there are limits to use ActiveRecord Models. The main idea is: There’s no business logic inside a Model. This has implications, mainly for Callbacks and Validations, as I will explain now.

Note: In our micro services, most of the times we have two kinds of validations: API Validations and Use Case Validations. API Validations are used to ensure that you send all the required data with right types to the endpoint, when it fails the server replies with a 400 bad request.

Use Case Validations ensure that the data you send has the right value to execute the Use Case. Normally, if these fails, the endpoint returns 422 Unprocessable Entity or 409 Conflict.

ActiveRecord callbacks normally have some kind of business logic. Sometimes you need to transform a value, others you need to send an email… please don’t. Callbacks are part of a particular Use Case, for instance, if you need to create a token for a User before create, that’s responsibility of the User::Create Use Case.

How many of you have a User model like this (or worse)? We all know where this class is heading.

ActiveRecord validations are awesome, but they are not part of a Pragmatic Entity. You only know what kind of validations you want to do, when you’re working with an Entity in a certain context. It’s the same idea from callbacks, if you need to validate a User before create, your run the User::Validate Use Case before calling User::Create.

Even after extracting all the business logic, validations and callbacks to Use Cases, there’re still Scopes, Associations and the main ORM API to query and interact with the database. Methods like .create, .find, .update_attributes, will be around our code base using ActiveRecord or other kind of persistence implementation. So, as a common interface that it is, is part of a Pragmatic Entity, just like Scopes and Associations.

This is the business logic extracted from the model:

This time I’ve used the RestMyCase gem from @goncalvesjoao for this example.

Wrapping Up

Decoupling database access from Entities is not our main concern right now. We managed to reduce our Entities to a level that we feel comfortable with and we see many advantages of accessing the database from it.
Mostly because it gives us coding freedom on a day by day basis.

If you have any questions you can reach me via twitter @joaquimadraz!