Search for a command to run...
One that actually adheres to Clean Architecture
Teddy is a full-stack Software Engineer.
He has experience as a Developer, Lead Developer, and teacher. Previously, he had the opportunity to work on projects at scale, in industries like pharmaceutical or e-commerce.
His mission here is to provide you with learning materials he didn't have so you don't waste time in your software journey.
No comments yet. Be the first to comment.
Are Go performance the real deal?
Generate insightful benchmark with Artillery.io
What is Clean Architecture and why it's desperately needed
What are components and how to organize them efficiently
Similarly to my Front-End implementation, I'm not satisfied with the available resources related to Clean Architecture. That's right, even on the Back-End!
If you stumbled upon this article, you probably know about Clean Architecture, but are looking for more information.
In the rare event of a beginner reading this article, I highly recommend getting started with the necessary theory.
While I wrote this article, my goal was to test if Clean Architecture was as flexible as it promised. That's the reason I re-used the same entities and use cases as my Front-End implementation, and tried to move the infrastructure part to the Back-End with Express.
That means, the application is the same: a Tic-Tac-Toe game (in TypeScript). You will be able to send requests to a Back-End and play a complete game.
If you want to follow along with me, you can clone my starter project.
You can find the Front-End Tic-Tac-Toe on CodeSandbox to understand what the application is doing in practice. There are two main functionalities:
Obviously, you can play a game of Tic-Tac-Toe.
You can go back to a previous move (history) and play again.
Instead of being a Front-End application, we will provide endpoints with the same behavior.
The original application already follows the idea of Screaming Architecture, with three directories:
common/ includes all the shared source code.
core/ defines the entry point of our application:
app.ts contains the ExpressJS server.
bootstrap.ts uses the code inside app.ts to build a server and listen to it.
tic-tac-toe/ contains everything related to the game itself.
While you can have a look at the entire project by yourself, please note there are three main files:
App
createApp is responsible for building the ExpressJS server and uses the Tic-Tac-Toe module (which is responsible for routing but is not the focus of this article).
Tic-Tac-Toe Controller
TicTacToeController is responsible for handling requests. It's the one that contains the business logic and the core part of the original implementation.
Board Service
BoardService takes the role of a data access object, which is an in-memory implementation for simplicity.
Similarly to my Front-End implementation, I like to start by defining a clear Domain Model. Its goal is to define the elements that make up our system. Please, keep in mind this is not strictly a part of Clean Architecture but Domain-Driven-Design.
For our game of Tic-Tac-Toe, we need:
A board composed of 9 squares.
Players and winners.
At one point in time, the state of our game:
Is there a winner?
The history of moves (so we can navigate among them).
Who is playing next?
Potentially, the index of the last game played.
I'll create this file under tic-tac-toe/, using a namespace to make it clear:
We will create an entity and use case in a minute. We can create the base classes for them under common/:
Keep in mind:
There are multiple ways to define those.
For
Entity, I like to store properties inside a_dataobject and make it protected. It prevents developers from mutating it directly, which is a common source of issues. Depending on our needs, this class will definitely change.There are multiple practices when it comes to use cases, but a very common one is to provide an
executemethod, which returns aPromisemost of the time.
Most of the logic of the Tic-Tac-Toe game seems related to the state of the board. Let's create an entity for it, inside a new entities subfolder, under tic-tac-toe:
Here:
We store squares, based on the types from our GameDomainModel.
We already have the formula to calculate if player X plays next.
We copy it from the TicTacToe file inside the starter project.
We can calculate the current step based on the filled squares.
The entity is also a great place to calculate if there is a winner.
We can also copy the formula from the starter TicTacToeController file.
In "Clean Architecture", Uncle Bob says:
An Entity is an object within our computer system that embodies a small set of critical business rules operating on Critical Business Data.
In our context, our critical business rules are the rules of the game of Tic-Tac-Toe.
Now, we have everything we need to create an empty use case. We can get started with an obvious one, playing a move.
Obviously, it will take the square we play on. On the other hand, we also need to define the step we play on, as we can play on a previous move. Our use case will probably return an object similar to the game state:
We could probably use
GameDomainModel.GameStateasOutputhere. On the other hand, those objects may only seem familiar, and change for different reasons.
To be honest, the current code inside TicTacToeController is very similar to the future content of the Play use case. It might be because I created this project as another implementation, but the original project is still far from using Clean Architecture.
If you remember well, a use case shouldn't depend on a data access gateway from the Interface Adapters layer.
Instead of the current BoardService, I'll define an interface as a port and its implementation will be an adapter. I'll also use the definition of Repository instead of Service for consistency.
Let's start with the interface by creating a sub-directory ports/ under tic-tac-toe/, with a file called board-repository.port.ts:
Then, we can create an adapters/ sub-directory under tic-tac-toe/. Also, the previous BoardService shouldn't be called BoardRepository.
It's not the implementation of IBoardRepository, it's one among others. To be more precise, it's an in-memory implementation.
Let's create in-memory-board.repository.ts:
Before we go back to our use case, we need one more thing: exceptions.
If you look at the original TicTacToeController, you can see we throw exceptions when:
The step we are supposed to play on doesn't exist
We play on a square that's already taken
With Clean Architecture, we cannot throw exceptions that belong to the infrastructure layer (Interface Adapters & Framework and Drivers), from the use case layer.
Instead, we need to throw a Domain Exception, that is handled by the controller.
Let's define two exceptions, stored inside an exceptions/ sub-directory (itself inside tic-tac-toe/):
Now that we have our entity, repository, and exceptions, we can complete our use case. Most of the logic can be transferred from TicTacToeController, in handlePlay.
There are a few changes necessary:
Business rules are now inside the Board entity.
We rely on the IBoardRepository.
We throw a Domain Exception
This use case was added under tic-tac-toe/ in its own sub-directory use-cases/.
The process is similar for the two other use cases. We can retrieve most of the logic from the TicTacToeController but use our brand new Board entity and IBoardRepository.
Let's start with jump-to.use-case.ts:
Then, we can add initialize.use-case.ts, which is responsible for starting a new game:
The last part is definitely way easier in a Back-End environment. We simply need to:
Execute the right use case
If there is a Domain (or unknown) Exception, throw the related Application Exception
Otherwise, return the result with the right status code.
Same thing here, using dependency injection is definitely easy. Depending on the Back-End framework you're using, you will have different solutions (or you can setup your own with InversifyJS).
In this example, I manually instantiate and inject dependencies from app.ts:
If you look closely at our current controller, it's doing more than orchestration. It's also formatting data for moves, status, and squares, which is not really its role.
A better architecture would use a presenter instead. There are multiple ways to define a presenter. A common practice is to define a class with a format method.
Let's create presenter.ts inside common/:
Now, we need to define our actual presenter. It's supposed to present our game and return the related squares, moves, and status. Based on our current code, it needs the current history, winner, xIsNext, and step.
A controller shouldn't depend directly on a presenter but on its interface.
Let's create a game-presenter.port.ts inside tic-tac-toe/ports/:
Now, we can add the implementation, as game.presenter.ts inside tic-tac-toe/adapters/:
Now, we can expect our IGamePresenter inside the TicTacController constructor (which we instantiate and inject from app.ts). Then, we can remove the method related to formatting and instead use the presenter:
Your Back-End Tic-Tac-Toe game is now fully functional, and adheres to Clean Architecture! The domain (logic) is completely isolated from the infrastructure.
Feel free to look at the end result.
You would have no problem moving away from ExpressJS and using another Back-End framework like Fastify or NestJS. If you did, you wouldn't need to modify any code that's part of the domain layer.
Not only could you use another Back-End framework, but you could even make this game a Front-End application!