🛁Clean architecture

Architecture, clean as a whistle, and clear as day. No developers were harmed during the writing of this article.

The second thing, and very much cross-functional in regards to quality and stability, is having an understandable, concise and powerful software architecture.

It is not enough for code to work.

— From Clean Code by Robert Martin.

🎯 Example 1: You can see a clear taxonomy for how the overall project and the microservices are organized by simply browsing the folder structure and seeing how code is linked together. Let's look at the FakeUser service:

FakeUser
└───config
└───contracts
└───controllers
└───entities
└───frameworks
└───usecases

What we're seeing is a somewhat simplified Clean Architecture structure. One of several tenets of Robert Martin's Clean Architecture concept is to produce acyclic code. You can see that there are no cyclical relations in the Arkit diagrams. This, among other touches, means that our code is easy to understand, easy to test and debug and that it is easy to make stable, almost entirely by just logically organizing the code!

Like Martin, I'm also taking cues from Domain Driven Design, where we use the "entity" concept to refer to "rich domain models", as opposed to anemic domain models:

In Martin’s seminal [Patterns of Enterprise Application Architecture] book (2002), a Domain Model is defined as an object model of the domain that incorporates both behavior and data'. This clearly sets it apart from Entity Objects, which are object representations of only the data stored in a database (relational or not), while the behavior is located in separate classes instead. Note that this divide is not really a layering, it’s just procedures working with pure data structures.

— Source: Codecentric blog

Read more about the Anemic Domain Model anti-pattern on Martin Fowler's site.

🎯 Example 2: While the examples in the code part of this project may be a bit contrived (bear in mind that they need to balance simplicity with meaningful examples), you can see how the User entity (at src/FakeUser/entities/User.ts) has not just data, but also business logic and internal validation on all the different operations it can perform. There is no need to leak such internal detail anywhere else; the only thing we add to that scenario is that we externalize the validation logic so that those functions can be independently tested (for obvious reasons private class methods are not as easily testable).

To keep it short here, I'll just refer to Robert Martin's original post on clean architecture and Clean architecture for the rest of us for more details. Also, see Khalil Stemmler's article on how CA and DDD intersect if that floats your boat.

Clean architecture isn't a revolutionary concept: it's just the best and most logical realization (I feel) so far for questions around code organization that have lingered for decades.