Forem: Nicolas Lapointe

Introduction to the principles of clean architecture in a NodeJs API (Express)

Nicolas Lapointe — Tue, 21 May 2024 08:17:46 +0000

This is the fourth article in our series on clean architecture (the previous ones are listed at the bottom of the page), and we're getting more technical with an introduction to implementing the principles in a Node.JS API with Express.

Let's take a look at the overall structure of a project and the details of the main concepts (entities, adapters, injection...).

Organization of main directories

Let's start by taking a look at the general directory structure. As is often the case, all our API source code is grouped together in the "/src" directory. Next, let's take a look at the Core vs. Infrastructure distinction:

The heart of the application in "/core"

This is where use cases, business entities and business rules reside. Not dependent on any external framework or library, it represents the bare minimum needed to run our application: it's the functional core of our application. It is itself divided into several sub-directories.

Use cases

In "/core/use-cases", we find the business use cases. Each use case has its own typescript file with, if required, its own input and output types (what goes into the use case and what comes out). There are two schools of thought:

A sub-folder with a grouping of use cases. Example: A user subfolder in which I group all user cases.
All use cases at the root of use-cases, with no particular tree structure.

I personally prefer the second solution, all "flat", for the simple reason that you never have to ask yourself the question "where do I put / where has this use case been put?". A simple example: do you put a user's address in "user" or "address"? There are as many answers as there are developers, so you might as well not put a sub-folder!

An example of a use case that allows you to obtain a book by its id:



class GetBook {
  private bookRepository: BookRepository;
  private logger: Logger;

  constructor() {
    this.bookRepository = container.resolve<BookRepository>('BookRepository');
    this.logger = container.resolve<Logger>('Logger');
  }
  async execute(id: string): Promise<Book | 'BOOK_NOT_FOUND'> {
    this.logger.debug('[Get-book usecase] Start');
    const data = await this.bookRepository.findById(id);
    return data ?? 'BOOK_NOT_FOUND';
  }
}
export default GetBook;

Entities

The "/core/entities" directory contains our business data models, such as "User" or "Product". These are simple objects that represent the concepts of our domain, and bring together their business rules.

Let's take the example of our "User", and more precisely of a user who is not logged in, and therefore not known to the API:



export class NotExistingUser extends User {
  constructor() {
    super();
  }

  public hashPassword(notHashedPassword: string) {
    const hmac = createHmac('sha512', this.config.salt);
    hmac.update(notHashedPassword);
    return hmac.digest('hex');
  }
}

Here, we have a class that extends User and thus retrieves its properties, and a method that belongs to it, that is, "its" business rule: You hash a password (to create your account or connect to it).

Ports

These are simple interfaces linking the core and the infrastructure. They serve as a contract without any concrete implementation. You may find ports for technical dependencies, such as a logger, or for repositories (databases, etc.). An example of a User :



interface UserRepository {
  findByEmail(email: string): Promise<User | null>
  create(user: User): Promise<void>
}

This contract includes two methods, each with input and output parameters. The code part therefore knows what it will receive from the infrastructure, and vice versa.

Technical details in "/infrastructure"

At the same level as core is the infrastructure folder, which manages all the technical details such as data persistence and calls to external services. This is where the interfaces defined in core are actually implemented.

The API

Let's start with the API, the folder in which we'll put Express' config, controllers and other middleware.

In detail, for controllers, the "/infrastructure/api/controllers" folder groups controllers by resource or use case.

Their role here is to retrieve data from the HTTP request, validate and map it to the inputs expected by the use case, execute the use case and finally format the response. We'll therefore find sub-folders for each resource, with a typescript file for the controller itself, the input and output DTOs, and the encoder/decoder for these inputs/outputs.

Adapters

As the name suggests, this directory contains the technical adapters for the ports defined on the core side. It's very important to identify implementation dependencies in the tree structure. Let's take our example of the User repository:



// /core/ports/user-repository.port.ts
interface UserRepository {
  findByEmail(email: string): Promise<User | null>
  save(user: User): Promise<void>
}

// /infrastructure/adapters/mongo/user.repository.ts
import { UserRepository } from '../../core/ports/user-repository.port.ts'
export class MongoUserRepository implements UserRepository {
  async findByEmail(email: string): Promise<User | null> {
  // logique d'accès MongoDB
  }
  async save(user: User): Promise<void> {
  // logique d'accès MongoDB
  }
}

At tree level, we find "adapters/mongo", which means that in this sub-directory we have all the technical implementation for accessing mongo DB. As you can see, the adapter takes over the contract specified in the port. If tomorrow I want to change my dependency to SQLite, for example, I'll simply create a second adapter, change the dependency injection, and there'll be no impact on the core.

Conclusion

This structure clearly distributes the various responsibilities of a Node.js API. The core has no external dependencies, ports are decoupled from business logic and implementation details are delegated to the infrastructure layer.

By following these Clean Architecture principles, your code gains in maintainability, testability and scalability. Although the example is given with TypeScript and Express code, this organization can easily be adapted to other Node.js frameworks or even any other language.
In the end, that's the whole point of clean architecture: no language or framework, but a return to basics, to common sense, and contrary to popular misconception, a return to simplicity!

Frequently Asked Questions:

What are the advantages of following Clean Architecture principles in an Express project?
The disadvantage of Express (or advantage, depending on your point of view!) is that it's an empty shell. So you can do absolutely anything you want, and also anything at all. Clean architecture provides a framework for the whole team.
If I'm doing clean architecture, do I have to follow this structure to the letter?
No, this structure is just one example. The most important thing is to respect the fundamental principles of Clean Architecture: separation of concerns, decoupling of technical details, external dependencies, etc.
How are tests structured in this architecture?
We haven't put it in this article, but use case unit tests can be put at the same level as each other, in /core/use-cases. Personally, I prefer to have a tests folder at the root, which is a convention we often see.

This article is an introduction to Clean Architecture and is part of a dedicated series on this topic. Stay tuned for more!

Want to learn how implement it with typescript and express? See my udemy course! In french or english 😉

Articles on Clean Architecture:

Clean Architecture: Business rules first!

Nicolas Lapointe — Mon, 13 May 2024 10:32:14 +0000

With this third article on Clean Architecture, let's go into a little more detail! The first article gave an overview of Clean Architecture, followed by a second on the separation between Core (business code) and Infrastructure (technical code). In this article, we're going to look at the Core part, and therefore the business rules, its central role in design and so as an essential (main!) element of Clean Architecture.

Obvious application behavior!

It seems obvious to say it: business rules and features are what govern the behavior of an application, and therefore its design. And yet... Many applications find themselves constrained by the technical aspect that takes precedence, or prevents a rule from evolving.

And that's exactly why I like Clean Architecture: we're simply putting back the basics, which existed years ago. It recognizes the value of business rules, and brings them to the fore. They're not just lines of code, but the pillars on which the design structure rests.

Let's delve into the foundations and examine how it ensures that business rules come first.

Business rules: the foundation of the application

Business rules represent the very essence of what an application does. They define how data is to be manipulated, what actions can be performed and under what circumstances. In short, they are the rules of the game that dictate the application's behavior in all possible situations.

And they must directly influence the way an application is designed and implemented. Quite simply, they must guide the architectural and structural decisions made throughout the development process.

Entities: bearers of business rules

At the heart of Clean Architecture are a set of entities, the main actors that embody the application's business rules from a code standpoint. They encapsulate data and essential business logic. If we take our theme from the play in the previous article, the entities would be the protagonists, carrying the weight of decisions and actions on their shoulders.

Role of entities: Entities represent the fundamental objects of the business domain, such as users, products or orders. They capture the business rules specific to these objects, and ensure that they are respected at all times at this single point in the code base.
Entity independence: Entities maintain strict independence from technical details. They remain focused on their core responsibility: faithfully representing the business domain, that's all! This independence allows entities to evolve independently of the underlying infrastructure, guaranteeing their reusability and extensibility.

Let's take a look at an example of Typescript code for a :

export class ExistingUser extends User {
  private _id: string;

  constructor({ id }: ExistingUserConstructorArgs) {
    super();
    this._id = id;
  }

  public signAndEncodeUserAccessToken() {
    const accessToken = sign({ sub: this._id }, this.config.secret, {
      expiresIn: 86400, // 24 hours
    });
    return accessToken;
  }

  public get id() {
    return this._id;
  }
}

This entity, which represents an application user, includes a data element (id) and a method or business rule (access token generation).

Use Cases: Executors of business rules

Just as entities represent the central objects of the business domain, use cases direct the execution of rules by coordinating the interactions between the various players in the application - a master of ceremonies in itself!

Role of Use Cases: Use cases act as script writers, defining the actions users can perform and the responses the application must provide in return. They translate business requirements into concrete actions.
Coordination with Entities: In executing use cases, entities provide the data required to meet the specific business needs defined by each use case. In our theater, this is the coordination between our protagonists and the texts of the play's overall scenario, our application.

Let's look at another example from the code side, for a Use Case :

async execute(
    login: string,
    password: string,
  ): Promise<{ accessToken: string } | 'USER_NOT_FOUND'> {
    this.logger.debug('[Get-user usecase] Start');
    const notExistingUser = new NotExistingUser();
    const user = await this.userRepository.findByLoginAndPassword(
      login,
      notExistingUser.hashPassword(password),
    );
    return user
      ? { accessToken: user.signAndEncodeUserAccessToken() }
      : 'USER_NOT_FOUND';
  }

There's an execution method, which represents our scenario. What does this scenario do? It will use a method to retrieve a user from the database, and user entities to use business methods, such as the generation of an access token seen above.

Alignment with Clean Architecture

Clean Architecture recognizes the importance of business rules in application design. It puts these rules at the forefront of design, and ensures that every development choice is aligned with the application's business needs.

Modularity and scalability of Entities and Use Cases

The application's entire business logic is based on entities and use cases. Designed to be modular and scalable, they provide a solid basis for development.

Modularity: Entities and use cases are designed to be easily modifiable and extensible. This modularity means that new functionalities can be added or existing ones modified without compromising the integrity of the application.

Scalability: Entities and use cases are also designed to evolve with the changing needs of the application. For example, the addition of a new business rule can be easily integrated without disrupting existing parts of the application.

Robustness and scalability

This modular, scalable design of entities and use cases naturally leads to greater robustness and scalability of the application.

Robustness: Because business logic is isolated from the rest of the application, Clean Architecture ensures that business rules are applied consistently and reliably. This reduces the risk of errors and bugs.

Scalability: Modularity and scalability, and therefore adaptability to future growth in functionality or other developments. Clean Architecture provides a solid foundation on which to build and extend the application over time.

Maintaining alignment with business needs

By always keeping an eye on business needs, Clean Architecture ensures that application development remains aligned with them. This approach ensures that every feature developed responds directly to a specific business need, guaranteeing the application's relevance and added value.

This article is an introduction to Clean Architecture and is part of a dedicated series on this topic. Stay tuned for more!

Want to learn how implement it with typescript and express? See my udemy course! In french or english 😉

Articles on Clean Architecture:

Clean Architecture : Infrastructure vs Core

Nicolas Lapointe — Mon, 06 May 2024 08:54:35 +0000

This article follows on from a more comprehensive presentation of Clean Architecture, which you can find here!

Imagine your application as a complex story between two essential protagonists: the Business Domain (Core) and the Technical Domain (Infrastructure). Their clear separation is the basis of Clean Architecture. Let's discover how this division, like a well-orchestrated score, optimizes the maintainability, scalability and clarity of your code.

In the complex world of application development, Clean Architecture stands out for its ability to clearly separate the business domain (Core) from the technical domain (Infrastructure). In this article, we'll explore in detail the separation between Core and Infrastructure that ensures better management of software complexities, as well as the importance of use cases as drivers of business rules.

Understanding the separation: Core vs Infrastructure

Before delving into the details, it's essential to understand the nature of this separation. Core represents the very essence of the application, where business rules and key concepts reside. Infrastructure, on the other hand, encompasses the technical details, such as database access or the management of external dependencies. This clear distinction ensures efficient management of the different aspects of your application: technical constraints are not mixed up with business rules.

The Business Domain (Core)

The Core is the rampart of business logic, where entities and use cases reside. Entities represent the key objects of the domain (the “core elements”, what we “present” to the business), while use cases direct the execution of business rules. This layer is the heart of the application, guaranteeing consistency and clarity of functionality.

The core can be divided into 2 layers: entities and use cases. Let's start with the first layer in the Core, Entities.

Nature of entities

Entities represent the fundamental concepts of the business domain. They encapsulate essential data and business rules, ensuring the consistency and integrity of information. Think of them as the main actors in a play, each with a defined role to play in the story.

For example, in an order management application, an entity might represent an order or a product.

Entities maintain strict independence from technical details, guaranteeing their reusability and scalability. This clear separation enables developers to concentrate fully on business logic without being distracted by technical considerations.

Compare this to the separation between the script of a play (Core) and the sets (Infrastructure) - the show can evolve without altering the main plot.

Image from Freepik

Role of Use Cases

Use cases describe the application's functionality from the user's point of view. They coordinate the actions performed by entities to meet the application's functional requirements.

For example, a use case might be “Create a new order” or “Modify product details”.

Use cases also maintain a clear separation from Infrastructure, focusing solely on business logic. This approach enables agile scalability, where functionality can be added or modified without disrupting the application's structure.

The Technical Domain (Infrastructure)

Conversely, the Infrastructure is the technical backdrop to your application. It manages everything behind the scenes, from databases to external frameworks, ensuring that the Core remains isolated from the technical details. It will never encroach on business logic. It's like a discreet orchestrator, ensuring that technical details never compromise the clarity and simplicity of the core scenario.

Think of this layer as the production team in the movie world, ensuring that the show runs smoothly while remaining invisible to the viewer.

Image de frimufilms sur Freepik

Technical Details Management

The Infrastructure also provides interfaces for interacting with these components. For example, rather than accessing a specific database directly, the Core uses an interface defined with the Infrastructure to interact with the data.

Separation of responsibilities

Finally, an essential feature of the Infrastructure is its ability to separate responsibilities. Each component is designed to perform a specific task, making it easy to maintain and evolve that part too. For example, a component responsible for data access can be easily replaced or upgraded without affecting the rest of the application or even the rest of the technical part.

Advantages of Core vs. Infrastructure separation

The clear distinction between Core and Infrastructure offers many advantages for application development.

Maintainability and scalability

By isolating the business logic from the rest of the application, Clean Architecture facilitates code maintenance and evolution. Changes made to the Infrastructure have no impact on the Core, enabling technical components to be updated or replaced without disrupting business functionality.

For example, you can decide to change the SMS sending partner, without any impact on the business code, which remains unchanged.

Clear understanding of the Code Base

The distinction between Core and Infrastructure makes the code clearer and more comprehensible. As I often say, the team PO can even have an eye on the Core part, without necessarily having a technical background.

Developers can easily identify which parts of the application are responsible for the business logic and which are responsible for the technical details. This facilitates debugging, collaboration and long-term maintenance.

Core and Infrastructure, the heart of Clean Architecture

Clean Architecture, with its distinction between Core and Infrastructure, offers a solid, structured approach to application development. By fully understanding this separation and focusing on entities and use cases as the pillars of the business domain, you can create applications that are robust, scalable and easier to maintain.

This article is an introduction to Clean Architecture and is part of a dedicated series on this topic. Stay tuned for more!

Want to learn how implement it with typescript and express? See my udemy course! In french or english 😉

Articles on Clean Architecture:

Demystifying Clean Architecture: Fundamentals and Benefits

Nicolas Lapointe — Thu, 02 May 2024 08:30:59 +0000

Imagine building a house with an inconsistent plan, where walls, roof, and foundations blend into a cheerful chaos... Well, that's exactly what the world of development can look like! Let's not kid ourselves; it happens (far too) often. We've probably all faced the spaghetti plate, a code where everything is mixed up and hard to maintain. Clean Architecture will be the master builder accompanying the construction of the house, bringing a framework that brings order to the increasing complexity of modern applications.

What is Clean Architecture?

Clean Architecture is not just a buzzword. Resulting from the work of Robert C. Martin (a publication in 2012 followed by a book in 2017 still available), it is an increasingly essential concept in modern development that offers a structured approach to designing robust, more easily maintainable, and scalable applications.
Let's first define the basics.

Definition

Clean Architecture aims to clearly separate concerns, with business aspects on one side and technical aspects on the other. It also aims to maintain essential control over dependencies, avoiding being tightly bound or coupled to them.

These are the two fundamental principles:

1- Separation of Concerns
With Clean Architecture, imagine each element of your application having a clear and distinct role. Business logic doesn't mix with technical details. The application is divided into layers, each with its responsibility.

2- Independence of Frameworks and Tools
Here, flexibility is key. Your application must be agile and able to adapt to changes without compromising its stability. A significant security flaw in one dependency? GDPR constraint on another? No matter, adapting the code, replacing it with another dependency, should be painless.

The Layers of Clean Architecture

In the definition part, we discussed decomposing into several distinct layers, each with a specific responsibility and role, following the principle of isolation. Let's dive into the details.

The Entities Layer
Entities form the heart of domain modeling, business. They are the building blocks of your application, guardians of business logic, without worrying about technical details, data persistence, etc.

The Use Cases Layer
Use cases are like conductors of your application. They direct business logic and ensure that everything runs smoothly with coordination between different parts of the application. They clearly describe business logic scenarios. I like to emphasize that the Product Owner's perspective can be interesting in this layer!

The User Interfaces Layer (Interface Adapters)
In this layer, we deal with interactions with the outside world. User interfaces and adapters handle inputs and outputs, like a gateway between the application and external dependencies.

The Infrastructure Layer
Finally, the infrastructure layer is the lair of technology. It is responsible for interacting with databases, frameworks, and everything related to technical aspects.

Each layer is isolated, independent. To make them communicate with each other, we'll use what's called dependency injection.

Why Choose Clean Architecture?

Now that we've seen the fundamentals and understand the basics, let's look at the concrete advantages of Clean Architecture principles.

Better Maintainability & Scalability
Our master builder has fulfilled its mission, the house is well-designed, and each room adapts to a single need. If I want to add a room or change a window, it's immediately simpler! Clean Architecture brings this flexibility, allowing the application to adapt and grow without difficulty. Unlike spaghetti code, where pulling on one side causes crashes elsewhere.

Better Testability
It's quite logical that with the principle of isolation, separation of concerns, where each layer has its responsibility, the code structure facilitates the implementation of unit tests. Simple elements lead to simple tests, simple tests mean more robust code.

Technical Independence
Still in our house, think of being able to change furniture without affecting the basic structure. This is exactly one of the fundamental principles of Clean Architecture, the independence of the technical layer. If changing the table requires changing the tiles, two walls, and three windows, it's immediately another project!

Clearer Understanding of the Code Base
By following the principles of separation of concerns at the code structure level, developers find a clear path within and between each layer, facilitating the understanding of the different parts of the application.

Disadvantages?
Of course, as often in the world of development, everything is not black or white. If we have advantages, we have disadvantages too: More complexity in development, a slightly steeper learning curve, it can be interesting to climb a few steps by following training. We can also add a larger source code size, or what can be considered as overdevelopment, and complexity during the initial configuration.

To Conclude

Clean Architecture is not just a development method; it is a philosophy that changes the way we design our applications. By adopting its principles, we ensure developing robust, scalable, and easier to maintain applications. And inevitably, it's also an improvement in the developer experience, which we'll address in a separate article.

But it's not a magic solution either! It's a development architecture, like others, and like others that will come tomorrow. It's up to you to determine if Clean Architecture is a good choice for your project, your context. In one of my experiences, we developed a POC, with the aim of validating a market and Web 3 technical specifications. We were moving forward without real functional specifications; each day brought, removed, modified a feature: It would have been too expensive to ensure having a clean structure for code that we had already planned to "discard."

But anyway, with the rise of generative AIs or Low Code / No Code applications (and both at the same time tomorrow?), the market share of applications developed with a tool will continue to grow and take its place, that's my conviction. Any application that doesn't fall into this category will inevitably be more complex, will require addressing challenges that Low Code / No Code or AI cannot solve. So, it will necessarily require a solid, robust, scalable, maintainable structure, everything that Clean Architecture offers today, and why not a new method or new principles tomorrow!

This article is an introduction to Clean Architecture and is part of a dedicated series on this topic. Stay tuned for more!

Want to learn how implement it with typescript and express? See my udemy course! In french or english 😉

Articles on Clean Architecture: