Trébol Backend Monolith

A monolithic backend web application for the eCommerce project Trébol, built using Spring Boot v2.6 and since then migrated to Spring Boot v3.2.

Current Status

Although some time has passed since I started working on Trébol, it is still far from a complete project. I have learned many things in the process: from design patterns to working with the intricacies of Spring Boot Web application. I've also gotten better at Git itself.

Recently, this project has been set up to work with Java 17, and as such, the artifact id of the project was changed too.

Currently, this backend implementation is aligned to Trébol API v1.7.2. It is planned to migrate towards version 3.0.

Please take a look at the CHANGELOG file to review 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
  • Here's a list of compatible IDEs and their installation guides to get yourself an instance running in no time
• Uses Spring Data JPA
  • Annotated entity classes; including constraints and indexes where they are most needed at scale
  • Bundles drivers for H2 and MariaDB; can virtually connect to any JDBC-compatible database with the correct driver
• Uses Spring Security
  • Implements stateless session authentication/autorization through JSON Web Tokens with aid from the JJWT library
    • Paired with users, roles, and permissions database tables
      • See data.sql for an example setup with 4 roles and users)
    • Do note that Authorities required in some 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 quite-evident properties, and provides a throughfully-explained example file with them, with sane defaults for quickly testing in your local machine.
  • Mission-critical
    • WebpayPlus properties
    • Mailgun & general mail properties
  • Security-crucial
    • CORS mappings
    • JWT secret key and duration
    • BCrypt algorithm strength

Data model diagram

This Entity-Relationship model diagram was designed quickly using Azimutt.

Getting started 👍

Requirements

• A supported version of the JDK
• Apache Maven 3

Supported JDK versions

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

Installation

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

After cloning the repository, run mvn verify, get yourself comfortable and wait until it is done. That command will:

• Download & install dependencies
• Generate some of the source code
• Compile the project
• Generate the WAR package file
• Install it to your local maven repo
• Run unit tests
• Check code coverage

An important step here that may confuse some people is the generation of 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 included through a Maven plugin within the project dependencies.

If for any reason you fail to compile the project, please try running mvn clean generate-sources instead and 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!