Developer Guide - rlossec/planet-pulse GitHub Wiki

1. Introduction

Contexte

PlanetPulse is a startup specialising in ecology and environmental monitoring. The company wants to develop a web application to track various environmental indicators by country, such as CO₂ emissions.

The mission is designing a functional prototype of this web application, implementing, testing, and deploying it for a product presentation to investors.

Project Arborescence

├── README.md
├── .gitignore
├── backend/
│   ├── pom.xml
│   ├── mvnw, mvnw.cmd, .mvn/
│   └── src/
│       ├── main/
│       │   ├── java/co/simplon/planetpulse/
│       │   │   ├── PlanetPulseApplication.java           # Entry point
│       │   └── resources/
│       │       └── application.properties
│       └── test/java/co/planetpulse/                     # Same arborescence
├── frontend/
│   ├── index.html
│   ├── css/
│   │   └── app.css
│   └── js/
│       ├── pages/
│       │   └── indicator/            # each page is a folder and contain 3 files (html, css, js)
│       |       └── Indicator.js
|       |       └── Indicator.html
|       |       └── Indicator.css           
│       ├── components/               # each component is a folder and contain 3 files (html, css, js)
│       │   ├── app-navbar/
│       │   └── indicator-table/
│       |       └── IndicatorTable.js
|       |       └── IndicatorTable.html
|       |       └── IndicatorTable.css 
│       └── utils/
│           └── api.js
├── database/
└── docs/
    ├── mcd/
    └── excalidraw/                           # Draft  diagrams

Documentation

Documentation should be maintained both in the project documentation and directly in the code when appropriate.

Java code should be documented using Javadoc when the purpose or behaviour of a class, method, or public API is not self-explanatory.

2. Configuration

Backend

Java 25
Spring Boot 4.1.1
Maven 3.10.0
JDK : 25.0.4

Frontend

Native JavaScript
Hybrid MPA/CSR approach
JavaScript modules and Web Components
Mandatory UI libraries:
- Bootstrap
- Bootstrap Icons
- Google Fonts
Use the latest available versions of the required frontend libraries.

Database

PostgreSQL 18

Development Tools

IntelliJ IDEA
Postman

3. Getting started

Clone the repository
Install dependencies
Environment variables
Database setup
Run the application

4. Development workflow

Modelling
Branching strategy
Commit conventions
Branching Workflow
Pull requests
PR & Code review

4.1. Modelling

The modelling process is divided into the following steps, order for guidance purposes only :

Take a Product Owner issue.
Create a development sub-issue.
Analyse the Product Owner issue.
Write and validate the business rules.
Create the data dictionary.
Create the Merise MCD.
Create the zoning.
Create the wireframes.

Detailled process

The development should start only after the requirements and modelling elements necessary for the task have been sufficiently clarified.

4.2. Branch Strategy

The project follows a Git Flow-inspired branching strategy.

The main development branches are:

develop: integration branch for completed development work.
integration: branch used to integrate and validate the current development state.

Feature branches are created from develop.

4.3. Commit Conventions

Commit messages must follow this format:

[category] Description #<issue_number>

Category	Description
`frontend`	Frontend-related changes
`backend`	Backend-related changes
`database`	Database schema, queries, or migrations
`scripts`	Scripts and automation
`docs`	Documentation updates
`test`	Tests and test-related changes

Examples

[docs] Add README.md #1
[backend] Add endpoint /users #12
[frontend] Add login page #8
[database] Add users table #5
[test] Add unit tests for authentication #15
[scripts] Add database setup script #7

:warning: Include the issue number (#<issue_number>) whenever the commit is related to an issue.

4.4. Branching Workflow

Follow this workflow when developing a new feature:

Create a feature branch from develop.
Develop the feature on your feature branch. Commit your changes following the commit convention.
Merge the feature branch into develop once the feature is complete and validated.
Open a Pull Request from develop to integration to integrate the changes.

4.5. Pull request & Code Review

A Pull Request should include enough information for another developer to understand what was changed and how the changes were validated.

Pull Request Template

## Description

Description of the modifications

## Changes

- Add ****
- Refactor ***

## Checklist

- [ ] Code follows project conventions
- [ ] Documentation updated
- [ ] No unrelated changes included

## Related issue

Closes #<issue_number>

The developer who creates a Pull Request cannot be the reviewer of that same Pull Request.

A code review is a discussion between the developer who created the Pull Request and the reviewer.

The reviewer may:

ask for clarification;
point out potential issues;
request changes when project conventions or coding principles are not respected;
suggest improvements when they are relevant to the task.

Everyone involved in the review should make an effort to explain their opinion clearly and support their suggestions with precise arguments.

Once the PR is merged : delete the feature branch.

5. Coding Guidelines

Naming conventions
Code style
Architecture principles
Error handling
Documentation

Naming conventions

General

Constants use UPPER_SNAKE_CASE.
The user interface is written in English.
Source code is written in English.
Names should be explicit and meaningful rather than abbreviated.

Java

One public class per file.
The file name must match the class name.
Classes use PascalCase.
Methods and variables use camelCase.

Examples:

public class UserService {

    private static final int MAX_RETRY_COUNT = 3;

    public User findUserById(Long userId) {
        // ...
    }
}

JavaScript

Files and directories use kebab-case.
Classes use PascalCase.
Functions, methods, and variables use camelCase.