Real clean architecture api example

An example of how to model and develop using clean architeture, to create a microservice to handle credit cards features from a fintech app, this is a learning exercice.


In this case I present a modeling scenario of a microservice created with nodejs and typescript. Simulating to be the backend of a credit card feature.
We will work as a base using the DDD methodology.


  • Node.js
  • Express js
  • Typescript
  • Docoker
  • Postresql


Follow this steps to install the project

npm install
docker-compose up -d
npm start

Run the script /data/tables.sql to create tables in the databas.


Before starting with software issues, following the principles of DDD, we must determine which will be our domain to solve.
Let’s imagine that we have several user stories that define the following behavior for us.

  • Feature 1 / card request:
    As a customer I want to be able to request my credit card, indicating what customizable icon it will have.

  • Feature 2 / card pause:
    As a customer, I want to be able to pause my credit card so that I do not have consumption.

  • Feature 3 / card reactivation:
    As a customer I want to be able to activate my previously paused credit card in order to continue making purchases.

Data definition:

We know that the data we handle on the card are the following:

    client:client who request the card;
    opExternal:Card provider metadata;

Data definition:

With this we can already assemble the first entities of our domain. You can take look here /src/domain/card.ts.


Once the domain has been analyzed, it is time to think about our layers, following the style of clean architecture, the layers look different from traditional configurations.

For this scenario we have assembled the following layers that can be seen in the diagram.

Layer by layer:

  • Domain:In this layer is where we will put the entities, value objects and business rules.
  • Application:Application: This is where functionality really lives, application logic is included.
  • Interface: Here we put the communication layer between infrastructure and application.
  • Infrastructure: Here we put the part of the system that has contact with the outside, eg: BD, 3rd party libraries, integration with other services, configurations. The idea of ‚Äč‚Äčthis layer is to be able to have contact with this layer through abstractions.

To use:

Follow this steps to install the project

Request card:

Run the following curl to make a card retrieval.

curl --location --request POST '' \
--header 'Content-Type: application/json' \
--data-raw '{

Pause card:

Run the following curl to make a card pause.

curl --location --request PATCH '' \
--header 'Content-Type: application/javascript' \
--data-raw '{

Activate card:

Run the following curl to make a card reactivation.

curl --location --request PATCH '' \
--header 'Content-Type: application/json' \
--data-raw '{


This is just the beginning, of a topic that is gigantic, I recommend that you review some of these links that I collect to put together this project.


View Github