Trébol Backend Monolith

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

Current Status

Although some time has passed since I started working on Trébol, it is still in an early version. I have learned many things in the process: design patterns and their limits; several details and how-to's going about Spring Boot; and also usage of other libraries (see Features below) and even Git itself.

Currently, this backend implementation is aligned to Trébol API v1.7.2.

Recently, the artifact, group and version of the project as described in the Project Object Model file were changed. The roadmap from here on isn't totally defined, but conditions to reach v1.0 are certainly stricter than before.

If anything, the foremost priority as of now is to warrant that the basic functionality is implemented correctly, with the aid of thorough unit testing.

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 /src/main/resources/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 very quickly using Azimutt.

Getting started 👍

Supported JDK versions

Java version	Supported?
11	✅ yes
12	✅ yes
13	✅ yes
14	✅ yes
15	✅ yes
16	✅ yes
17	✅ yes
18	✅ yes
19	🔴 no
20	🔴 no
21	🔴 no

Requirements

JDK 11+
Apache Maven 3.6.0

Installation

First, 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

The important step here that may confuse some people is to generate some of the source code. It is made this way because some classes (QueryDSL types such as QUser, QProduct and so on) are unversioned and only included through a Maven plugin within the project dependencies.

If for any reason you fail to compile the project, please run 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 at /src/main/resources/application.properties. These are sane, briefly documented defaults. Play around if you'd like.

You can run the application out-of-the-box with these, though you should have a good look at it.

Also remember, that Spring Boot does support using more than one profile at once. This and this section of the Spring Boot guide 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} 📖