This project is a simple Node.js boilerplate using TypeScript and Docker. It demonstrates vertical slicing architecture for a REST API, as detailed here: https://markhneedham.com/blog/2012/02/20/coding-packaging-by-vertical-slice/. Unlike horizontal slicing (layered architecture), vertical slicing reduces the model code gap, making the modeled domain easier to understand. The implementation also follows the principles of Clean Architecture by Uncle Bob: https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html.
The application provides APIs for users to view, create, update, and delete todos (CRUD operations)
todo-api
├─ package.json
├─ src
│ ├─modules (domain components)
│ │ ├─ todos
│ │ │ ├─ tests
│ │ │ ├─ repository
│ │ │ ├─ routes
│ │ │ ├─ controllers
│ │ │ ├─ *.service (business logic implementation)
│ ├─ users
│ ├─ ...
│ │
├─ infra (generic cross-component functionality)
│ ├─ data (migrations, seeds)
│ ├─ integrations (services responsible for integrations with 3rd party services - belong to repository layer)
│ ├─ loaders
│ ├─ middlewares
The application uses the winston
logger for effective logging and the cls-rtracer
package to provide cross-layer trace IDs. As a result, logs related to the same request but from different layers (service, repository, controller) are outputted with the same trace ID without any extra implementation.
Console Output
:
info 07/21 15:26:16:742 [928aa440-4775-11ef-a88a-7b1736b24e71] GetTodos:execute
info 07/21 15:26:16:743 [928aa440-4775-11ef-a88a-7b1736b24e71] TodosRepository:findAll
info 07/21 15:26:16:806 [928aa440-4775-11ef-a88a-7b1736b24e71] createController:completed
Please make sure that you have docker installed https://docs.docker.com/engine/install/
How to run locally (in dev mode):
- Copy
.env.sample
and rename it to.env
, providing the appropriate environment variable values. Some of the variables are defined in the docker-compose file - Install dependencies locally
npm i
- Start the app using
npm run docker:run
- By default, the API server is available at
http://localhost:8080/
Migrations and seed run automatically
How to run tests in separate docker containers locally:
- Install dependencies locally
npm i
- Run API tests in separate docker containers
npm run docker:test
Here is Postman collection to work with API locally: