Todomi API

Introduction

This API is dedicated to the implementation and exploration of Hexagonal Architecture.

Hexagonal Architecture, also known as "Ports and Adapters" or "Onion Architecture", is a software design pattern that emphasizes the separation of concerns in a system by separating the external interfaces from the internal implementation.

This simple todo list API is made to understand the hexagonal architecture concept with simple features.

This results in a flexible and easily maintainable architecture that can be adapted to changing requirements with minimal impact on the rest of the system.

Hope it can helps :)

Technologies used

Back-end

• NodeJS
• Express framework
• Typescript
• Jest & Supertest
• Swagger Express UI
• Git versioning

Database

• PostgreSQL deployed in a Docker container (in a VM)
• pgAdmin4 (GUI)
• MongoDB for testing adapter on host

Hexagonale architecture or Ports and Adapters Architecture (Alistair Cockburn)

Folder structure

├── package-lock.json
├── package.json
├── README.md
├── restClient.http
├── src
|  ├── app
|  |  ├── adapters
|  |  |  ├── primary.driver
|  |  |  |  ├── controllers
|  |  |  |  |  ├── article.ts
|  |  |  |  |  ├── coreController.ts
|  |  |  |  |  └── main.ts
|  |  |  |  └── routes
|  |  |  |     ├── article.ts
|  |  |  |     ├── index.ts
|  |  |  |     └── main.ts
|  |  |  └── secondary.driven
|  |  |     ├── database
|  |  |     |  ├── mongodb.ts
|  |  |     |  └── postgresql.ts
|  |  |     ├── repositories
|  |  |     |  ├── articleRepository.ts
|  |  |     |  ├── data
|  |  |     |  |  └── migration.sql
|  |  |     |  ├── mongo.datamappers
|  |  |     |  |  ├── article.ts
|  |  |     |  |  └── coreDatamapper.ts
|  |  |     |  └── pg.datamappers
|  |  |     |     ├── article.ts
|  |  |     |     └── coreDatamapper.ts
|  |  |     └── swagger
|  |  ├── core
|  |  |  ├── gateways
|  |  |  |  ├── interfaces
|  |  |  |  |  └── articleInterface.ts
|  |  |  |  ├── middlewares
|  |  |  |  ├── schema
|  |  |  |  ├── services
|  |  |  |  |  ├── errorHandler.ts
|  |  |  |  |  └── errorLoggerHandler.ts
|  |  |  |  └── utils
|  |  |  |     └── formattedDate.ts
|  |  |  ├── models
|  |  |  |  ├── articleModel.ts
|  |  |  |  └── coreModel.ts
|  |  |  └── use-cases
|  |  |     └── articleCRUD.ts
|  |  └── Types
|  |     ├── custom.ts
|  |     └── express
|  |        └── index.d.ts
|  ├── index.ts
|  └── __tests__
|     └── article.test.ts
├── tsconfig.json
└── __docs__
   ├── media
   |  └── test.png
   └── test-jest.md

Steps to use this repo

Get started

You need to install :

• Nodejs
• PostgreSQL

Need to add a .env file and configure with your own environment variable :

#MY_PORT=VALUE
PORT=#

#INFO CONNEXION DB FOR PSQL new Client()
PGHOST=#
PGDATABASE=#
PGUSER=#
PGPASSWORD=#
PGPORT=#

You'll find all the details in the file migrations.sql for deploy a basic database and some datas :

--====================================
-- Create DB and table
--====================================

DROP DATABASE taskedo;

CREATE DATABASE taskedo;

--=======================================================
-- CONNECTO DB taskedo before launching these commands
--=======================================================

CREATE TABLE article (
    "id" INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    "content" TEXT NOT NULL,
    "created_at" TIMESTAMPTZ DEFAULT now(),
    "is_done" BOOLEAN DEFAULT false
);

--====================================
-- Insert some values
--====================================

INSERT INTO article ("content", "created_at")
(
	SELECT
		('task' || ' ' || serie_nb),
		(now() + interval '23 hours')
	FROM generate_series( 1, 9) as serie_nb
);


--========================================
-- Create 2 functions create and update
--========================================

CREATE OR REPLACE FUNCTION create_article(JSON)
RETURNS TEXT AS $$

    INSERT INTO "article"("content")
    VALUES (($1 ->> 'content')::TEXT)
    RETURNING "content";

$$ LANGUAGE SQL;

CREATE OR REPLACE FUNCTION update_article(JSON)
RETURNS TEXT AS $$

    UPDATE "article"
    SET 
        "content" = COALESCE(($1 ->> 'content')::TEXT,"content"), 
        "is_done" = COALESCE(($1 ->> 'is_done')::BOOLEAN,"is_done")
    WHERE "id" = ($1 ->> 'id')::INT
    RETURNING "content";

$$ LANGUAGE SQL;

• You'll find a file named restClient.http for testing your routes. To use it, you'll need to add REST Client VS Code extension (or you can use Insomnia, Postman etc...)

• The format for JSON to create or update a task is the following:

// to add a task
{
  "content": "task added !",
}


// for update a task, is_done is not required
{
  "content": "task updateeeeeed !",
  "is_done": true
}

Launch the app

Initialize :

npm init

Install all the dependencies :

npm i
#or
npm install

Launch the server in development environment :

npm run dev

Todolist

• Create a user and add connexion

---

Sources

• Training Wealcome with Michaël Azerhad
• Thanks to Alistair Cockburn for taking time to help me and let me redraw the diagram :)
• Original article of hexagonal architecture