Node.js Clean Architecture REST API

Welcome to the Node.js Clean Architecture REST API project! This project is designed to understand and practice Uncle Bob's Clean Architecture principles.

Project Overview

This application revolves around two main entities: notes and users. Authorized users have the ability to perform basic CRUD (Create, Read, Update, Delete) operations on note entities, and these actions are stored in a database. It also has refreshToken entity that is being used to allow users to regain accessToken after it expires.

Architecture Overview

1. Data Access Layer

• This layer connects entities to the use-case layer.

2. Use-Case Layer

• The use-case layer contains all the business logic for each entity.
• It relies on services, specifically the authService and validationService, which are injected into the use-case factory functions.
• This design prevents the use-case layer from depending on external libraries.

3. Controllers

• Controllers act as intermediaries, handling HTTP requests.
• They transform and pass the necessary data to the use cases.
• After processing, they receive results generated by the business logic of the application.
• Finally, controllers send responses back to the framework layer.

4. Frameworks and helpers

• This final layer (index.js file) handles errors, handles requests, and responses, connects to the database, generates documentation, etc.

User authentication flow

As mentioned at the beginning there is a third entity called refreshToken, which is generated alongside the accessToken when the /auth/login route is invoked. Both tokens are transmitted to the client via HTTP-only cookies. However, it's important to note that the refreshToken is also persisted in a database for specific reasons. The primary role of the refreshToken is to provide a means of maintaining user authentication even when the accessToken expires. This is achieved through the following steps:

1. Initial Token Generation :

• When a user logs in via the /auth/login route, both an accessToken and a refreshToken are generated.
• These tokens are sent to the client and stored in HTTP-only cookies for security.

2. Database Storage:

• The refreshToken is saved in a database for future reference and verification.

3. Token Expiry Handling:

• As time passes, the accessToken may expire due to its short lifespan.
• When an authenticated user attempts to make a request with expired accessToken, the middleware responsible for verifying user authentication intervenes.

4. Refresh Token Verification:

• The middleware initiates an Axios call to the /refresh-token endpoint to verify the refreshToken's validity.
• If the refreshToken is successfully verified, a new accessToken is generated and sent back to the user.

5. Failed Verification:

• If the refreshToken verification fails, indicating a potential security breach, the refreshToken, as well as any tokens stored in cookies, are deleted.
• This action effectively logs out the user and revokes their access.

API documentation

The whole API is documented using Swagger-jsdoc, you can get access to it by running this project on your machine and hitting /docs endpoint or simply see Postman collection under this link.

How to run this on your machine

# clone this repo 
git clone https://github.com/QuickerMaths/nodejs-clean-architecture

# install dependencies 
npm i

# rename .env.example file to .env

# run 
docker compose up

# start the local server 
npm run dev