Developer manual

Technology overview

Docker

Docker is an open-source platform designed to develop, ship, and run applications in isolated environments called containers. Containers bundle an application with all its dependencies, ensuring consistency across various environments (development, testing, production, etc.).

Documentation: https://docs.docker.com/

Docker compose orchestration

Docker Compose is a tool for defining and managing multi-container Docker applications. It uses a YAML file to configure application services, allowing developers to start all the required containers with a single command.

Documentation: https://docs.docker.com/compose/

React

React is a popular open-source JavaScript library developed by Facebook for building user interfaces (UI), particularly for single-page applications (SPAs). It allows developers to create reusable UI components, ensuring efficient and dynamic rendering of content.

We choose this to match the technology choice made by Mirador.

Documentation: https://react.dev/

NestJS

NestJS is a progressive, open-source Node.js framework for building scalable and maintainable server-side applications. It is built with TypeScript and heavily inspired by Angular's architecture, making it modular, extensible, and easy to organize.

Documentation:https://docs.nestjs.com/

MariaDB

MariaDB is an open-source, high-performance relational database management system (RDBMS). It is a fork of MySQL, created to remain free and community-driven. Known for its speed, scalability, and security, MariaDB is widely used for web applications, enterprise software, and embedded systems.

Documentation: https://hub.docker.com/_/mariadb

Setup development environment

Code folders overview

Guidelines

Avoiding circular dependencies with nestJS and linkTable

We have implement linkTable with one to many relation with over entities, this allow us to define rights for the entity A on entity B But this introduce circular dependency problem. I manage a structure to handle this.But it allow us to import module A and B into the link module but not the linkModule into module A or B. Module A and Module B take care of there own logic and Link Module handle the logic that concern A AND B modules.

Historic

We used to avoid this problem by creating a C module. This module imported module A & B & Link but this have for side effect to increese code base a lot, we decided to change this into this branch : https://github.com/SCENE-CE/mirador-multi-user/tree/backend-clear-useless-routes

Snippet of code showing the problem :

Here you can see that we import ProjectModule and UserGroupModule into LinkProjectUserGroupModule

It result into this error :

Scheme

Database migrations

Create a migration

• run the app with docker compose up
• connect to backend docker with docker exec -it <name-of-your-backend-container> /bin/sh
• run npm run typeorm:generate-migration --name=<name-of-the-migration>

Execute migrations

• docker compose up
• connect to backend docker with docker exec -it <name-of-your-backend-container> /bin/sh
• cd /app
• npm run typeorm migration:run -- -d ./src/config/dataSource.ts

Recreate Db in development (do NOT do this in PRODUCTION)

[TODO] Commpléter

Execute this comands into the backend docker :

• npm run typeorm:generate-migration --name=db-init
• npm run typeorm migration:run -- -d ./src/config/dataSource.ts

Promote a use to administrator of the platform

You can't promote a user to admin using the API or the UI so you MUST need to directly connect to the db and run this SQL request :

UPDATE multiUsers.`user`
SET `_isAdmin` = 1
WHERE id = <Replace this by the user you want to promote id>;