Trébol Backend Monolith

A monolithic backend web application for the eCommerce project Trébol, built using Spring Boot v2.6.

Since then it's been migrated migrated to Spring Boot v3.2.

Current Status

Recently, this project has been set up to work with Java 17, and as such, the artifact id of the project object model was changed to reflect on that.

Currently, this backend implementation is aligned with the Trébol API v3.0. But at the same time, this application includes endpoints that are beyond the scope of that API. These enable some important features:

• Registering an user account
• Logging in with said account
• Placing orders using a guest account
• Querying level of authorization per-module

Please take a look at the CHANGELOG file for full explanation on the most recent changes, additions and fixes.

Features

• Exposes a RESTful API and supports all the operations described by the document, such as:
  • CRUD operations on all declared data types.
    • Can filter, sort and paginate through query params.
    • Some endpoints support partial updates using PATCH requests.
  • Login, registration and optionally, guest customer accounts.
  • Checking out as a registered user or a guest (when enabled).
• Uses Project Lombok in all of its API models and JPA entities to reduce the amount of boilerplate code.
• Uses Spring Data JPA.
  • Includes annotated entity classes; specifying constraints and indexes where they'll be most likely needed when scaling up.
  • Bundles drivers for H2 and MariaDB, but can virtually connect to any JDBC-compatible database with the correct driver.
• Uses Spring Security.
  • Implements stateless authentication/authorization through JSON Web Tokens by using JJWT.
    • Constrained in tandem with database tables users, roles, and permissions.
      • See data.sql for an example setup with 4 roles and users.
    • Do note that the Authorities required in REST controllers are hard-coded. These must match entries in the permissions database table.
  • Passwords encoded with BCrypt by default.
• Integrates payments with WebpayPlus by Transbank (Java SDK repo).
  • It is planned to integrate more internationally popular payment services such as PayPal and Stripe.
• Integrates mail notifications with Mailgun (an account and API key are required).
• Defines self-evident application properties, and provides a throughfully-explained example file with them, with sane defaults for quickly testing in your local machine.
  • Mission-critical properties, such as...
    • Payments with WebpayPlus.
    • Mailgun & general properties for mail-related services.
  • Security-crucial properties; the likes of...
    • CORS mappings, should one need to remap the API.
    • JWT secret key and duration.
    • BCrypt algorithm strength for storing passwords.

Data model diagram

There was an Entity-Relationship diagram included in this part of the README file here, but after some of the recent, more heavy changes, it became outdated so it was deleted. It's not very good practice to store binary data in a version control system either...

However, please remember that this repo does contain the schema file to spin up a new database from. If you need/want to have a diagram to look at, I recommend trying Azimutt to create and design one from it. It's a powerful little program, really intuitive and easy to use too.

Getting started

Requirements

• A supported version of the JDK (see table below)
• Apache Maven 3

Supported JDK versions

Java version	Supported?
< 17	no
17	yes
19	compatible
21	compatible

Installation

First and foremost, please don't forget to download, install and enable the correct Project Lombok plugin for your IDE if you haven't done so by now.

After cloning the repository, run mvn verify and get yourself comfortable because it'll take a while. That command will:

1. Download & install dependencies.
2. Generate some of the source code.
3. Compile the project.
4. Generate the WAR package file.
5. Install it to your local maven repo.
6. Run unit tests.
7. Check code coverage.

One very important step that may confuse some, is no. 2, generating some source code. We have set up type-safe queries by relying on dynamically-created QueryDSL classes such as QUser and QProduct, which are un-versioned and only brought in to the code through a Maven plugin within the project dependencies.

So if for any reason you fail to compile the project, please reassure said step is successful by running mvn clean generate-sources first. Then try the former command again.

How to use

You can quickly run the application on top of an embedded server by executing the Spring Boot Run maven goal mvn spring-boot:run.

Integration with Mailgun will only be available if the mailgun Spring profile is active. Please read the application-mailgun.empty.properties file and this bit of the Spring Boot documentation to know how to proceed about said Spring profile.

Configuration

The default configuration properties are located in the default properties file. These are sane, briefly documented defaults. You can run the application out-of-the-box with these. You can also totally play around with them.

Also remember, that Spring Boot does support using more than one profile at once. The sections in the official guide that explain External configuration and Profiles can help you understand these mechanisms.

Contributing to this repository 😍

Please review the contributing guidelines before proceeding.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Amigoscode 🤔	bglamadrid 💻 🎨	Trang Nguyen 💻	Parundeep Singh 💻	Markus Mutas 💻	vaishakhvh 💻	Rod Fetalvero 💻 ⚠️ 🤔 🚧 👀
mepox 💻 🚧 🤔 👀	Shivam Purohit 💻	Ujwal Kumar 💻	angelmr 💻	Prashriya Acharya 💻	Loges R 💻	Marcin Słowiak 📖

This project follows the all-contributors specification. Contributions of any kind welcome!