Dev Handbook

Table of Contents

• Introduction
• Backend
  • Languages and Frameworks
  • Tools
    • Sdkman: Java & Maven version management
    • Nvm: Node version management
  • Developer’s agreements
    • Code style
    • Performance
• Frontend
• Git
  • Git workflow
    • Branch naming convention
  • Versioning (SemVer)
  • Conventional commits
  • Commitlint & husky
• Clean Code Checklist
• Development environment
• TODOs

Introduction⇧

This section provides an overview of the development practices and tools used in the project: GitHub Flow, versioning, frameworks, CLI tools, and more.
The project follows a microservice and feature-based architecture to keep the codebase modular and scalable.

Backend⇧

Languages and Frameworks

• Java 21
• Maven 3.9
• Node.js 22 (latest LTS at 2025-04)
• NestJS 10: latest major version (no LTS policy)
• Spring boot 3.3

Tools

Sdkman: Java & Maven version management

Sdkman can help to manage the version of different tools.

Installation:

curl -s "https://get.sdkman.io" | bash

Switching to the required version can be automated:

cat $HOME/.sdkman/etc/config
sdkman_auto_env=true

Note:To run skdman (you need to restart your terminal after the installation).

Exemple of configuration file: .sdkmanrc

cat .sdkmanrc
# Enable auto-env through the sdkman_auto_env config
# Add key=value pairs of SDKs to use below
java=21.0.4-oracle
maven=3.9.8  # Ajoute apres

To run skdman (you need to restart your terminal after the installation):

sdk env install

Nvm: Node version management**

Nvm can help to manage node.js version.
Switching to the target version can be automated by adding this snippet in .bashrc file.

Exemple of configuration file: .nvmrc

cat .nvmrc 
v22.14.0

Bash sample to automate the version switch:

autoload_nvmrc() {
  local nvmrc_path=$(nvm_find_nvmrc)
  
  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version=$(cat "$nvmrc_path")
    # If the current Node version is different from the one in .nvmrc, switch versions
    if [ "$(nvm version)" != "$nvmrc_node_version" ]; then
      nvm use
    fi
  fi
}

PROMPT_COMMAND="autoload_nvmrc; $PROMPT_COMMAND"

Developer’s agreements

Code style

The code in java should respect the Google Java Format.

• To check if the code is well formatted, you can use the mvn spotless:check
• To format the code, you can use the mvn spotless:apply

A naming convention for database tables has been adopted, with the aim of ensuring that table names are always in the singular.

Please respect the hexagonal architecture principles, which means that the code should be organized by feature and not by technical layer. This allows for better modularity and easier maintenance.

Performance

Try to optimize requests and responses, to lighten processing in services and limit the amount of non-essential data loaded into memory. For that, use DTOs projection and pagination when possible.

Use FetchType to limit the amount of data loaded in memory. For example, use FetchType.LAZY to load data only when needed, and avoid loading entire collections or entities unless necessary.

Frontend⇧

• Vue.js 3

TODO: complete the list of libraries eg. Pinia, VueQuery, etc.

Git⇧

Git workflow

The selected git flow is GitHub Flow.

Branch naming convention

We use the following branch naming convention: /-short-description

Examples:

• feat/123-add-login
• fix/456-fix-header

Versioning (SemVer)

The versioning strategy is Semantic Versioning.

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes

Conventional commits

The commit messages should respect the Conventional Commits specification.
This specification defines at least 2 types of messages, feat, fix and the notion of Breaking change.
This allow to automate the SemVer management:

fix             -> patch
feat            -> minor
Breaking change -> major

Commitlint & husky

In order to facilitate the commit with command line, commitlint can be used in conjunction to husky (client side git hooks).

Clean Code Checklist (cf Uncle Bob)⇧

1. Name things clearly: use explicit and meaningful names, void obscure abbreviations or acronyms.

2. Keep functions short: keep it small, ideally between 5 and 15 lines.

3. Cohesion and separation of concerns: respect the SRP (Single Responsibility Principle).

4. Remove dead code

5. Avoid unnecessary comments: code should be self-explanatory; comments should explain the why, not the how.

6. Clear error handling: no silent failures, use specific and explicit exceptions.

7. Consistent formatting(cf linter section).

8. Automated testing: clean code is testable, ensure reasonable coverage.

9. Avoid side effects: prefer pure functions, minimize implicit state mutations.

10. Regular refactoring: refactoring is part of the development cycle (Use barrels for ts).

Development environment⇧

The development environment can be installed with docker compose. It deploys the services needed for the development: authentication, databases, API Manager, etc.

• Repository: srv-dev
• Installation notes: Readme

TODOs⇧

Features templates by framework

• Spring-Boot
  • https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html
  • https://github.com/Muddz/StructurebyFeatureTmpl
• NodeJS NestJS
• Vue.js
  Note: for typescript use barrels to facilitate refactoring.

Linters by technos - TODO Fix configurations and tooling.

• Java: https://github.com/google/google-java-format
• NodeJS: ESLint + config TypeScript

• NestJS: ESLint + config TypeScript + NestJS

• Plugins: @typescript-eslint, eslint-plugin-import, eslint-plugin-prettier
• https://github.com/prettier/prettier
• Vue.js: eslint-plugin-vue