SooQ - An Advanced SpringBoot Server App Boilerplate for E-commerce Website

Support

If you like this project, consider supporting me on Patreon 💖

❤️ Thanks for supporting me!

---

Introduction:

SooQ is an advanced SpringBoot server app boilerplate designed to help developers build e-commerce websites with ease. It provides a solid foundation for your project, saving you time and effort in setting up the initial infrastructure.

SooQ built for scalability, performance, and security. It follows best practices and industry standards to ensure a robust and reliable e-commerce platform.

---

Features:

• Database Design: A well-structured database schema to store and manage project data, we use MySQL as the relational database. Please read the database readme file for more details.
• SpringBoot: A powerful and feature-rich framework for building Java-based applications. SooQ leverages the SpringBoot ecosystem to provide a solid foundation for your e-commerce website powered by Maven.
• MVC Architecture: Follows the Model-View-Controller architectural pattern to separate concerns and improve code organization.
• RESTful API: Provides a RESTful API interface for client applications to interact with the server.
• Security: Implements security measures such as input validation, authentication, and authorization to protect sensitive data.
• JWT Manager: A JSON Web Token manager to handle token processes.
• Middleware: An auth guard to filter the public and private routes using JWT.
• Environment Variables: Utilizes environment variables to store sensitive configuration information, such as database credentials and API keys.
• Testing: Multiple unit and integration tests for many methods.
• Dockerization: Easily containerize your application using Docker for seamless deployment and scaling.
• API Documentation: Well-documented API endpoints using Swagger to help developers understand and consume the API.

---

Usage

1. Download project

You can download the project by cloning the repository using the following command:

git clone https://github.com/hamzaelmarjani/sooq-api.git sooq
cd sooq

2. Set-up Environment

First set-up the database by following the instructions in the database readme file.

Next, set up the environment variables, set your database credentials and JWT secret in (.env) file, un example of the required variables can be found in the .env.example file.

Additional Setup:

Set the Jwt Expiration durations inside the main/resources/application.yaml file.

• Jwt Access Token Expiration: jwt.accessTokenExpiration (default: 3600 seconds = 1 hour)
• Jwt Refresh Token Expiration: jwt.refreshTokenExpiration (default: 2592000 seconds = 30 days)

3. Build and Run the Application

Build the application using Maven: (If you don't have it on your machine, download it via: Maven Installation Guide)

mvn clean install

Run the application:

mvn spring-boot:run

The application will start running on http://localhost:8080.

---

4. API Documentation

Once the application is running, you can access the API documentation using Swagger. Open your web browser and navigate to http://localhost:8080/swagger-ui/index.html.

---

Project Structure

The project follows a standard SpringBoot project structure. Here is an overview of the main directories and files:

• src/main/java: Contains the Java source code for the application.
• src/main/resources: Stores application resources, such as configuration files and static assets.
• src/test/java: Includes test classes for unit and integration testing.
• pom.xml: The Maven project configuration file that defines dependencies and build settings.

After you change the project artifactId from cc.hamzaelmarjani.sooq to yours, let's start exploring the project structure.

• src/main/java/cc/hamzaelmarjani/sooq/SooqApplication.java: The main entry point of the springboot application (you may want to change the timezone inside this file to apply on the whole app).
• src/main/java/cc/hamzaelmarjani/sooq/config: Includes configuration classes, such as security, swagger and JWT configuration.
• src/main/java/cc/hamzaelmarjani/sooq/controller: Houses the RESTful API controllers (user, product, order ...).
• src/main/java/cc/hamzaelmarjani/sooq/database/entities: Defines the data models and entities.
• src/main/java/cc/hamzaelmarjani/sooq/database/mappers: Defines the mapper interfaces for database access.
• src/main/java/cc/hamzaelmarjani/sooq/database/repositories: Contains the repository interfaces for database access.
• src/main/java/cc/hamzaelmarjani/sooq/dtos: Contains the data transfer objects (DTOs) used for communication between layers, as well as the request and response models.
• src/main/java/cc/hamzaelmarjani/sooq/exceptions: Handles the application exceptions and error responses.
• src/main/java/cc/hamzaelmarjani/sooq/filters: Contains the filters classes, such as JwtAuthenticationFilter.
• src/main/java/cc/hamzaelmarjani/sooq/services: Includes the business logic services.

---

Security

The API is secured using JWT (JSON Web Token) authentication. To access protected endpoints, you need to include the JWT token in the request Authorization header with the Bearer scheme.

But not all endpoints are protected, some of them are public, such as user registration, login and refresh.

To set the public endpoints, you need to add them to publicPaths array within the class: config/SecurityConfig.java.

    private final String[] publicPaths = { "/auth/login", "/auth/refresh", "/user/register" };

Otherwise all other endpoints are protected, and you need to include the JWT token in the request header to access them.

curl -X GET http://localhost:8080/auth/get-user -H "Authorization: Bearer <JWT_TOKEN>"

Replace <JWT_TOKEN> with your actual JWT token.

---

Docker

You can build the Docker image for the application using the provided Dockerfile.

docker build -t sooq-api .

Once the image is built, you can run the container, but first you need to make some set-ups:

• You need to use Docker’s special hostname host.docker.internal to connect to the host machine from within the container.
• You need to include the .env file as argument when running the container.
• You need to set the environment variables DATABASE_URL when running the container.

docker run \
  --add-host=host.docker.internal:host-gateway \
  --env-file /path/to/.env \
  -e DATABASE_URL=jdbc:mysql://host.docker.internal:3306/<database_name>?createDatabaseIfNotExist=true \
  -p 8080:8080 \
  sooq-api

Now, the application will be accessible at http://localhost:8080.

---

Contributing

Contributions are welcome! Please feel free to:

• Open issues for bugs or feature requests
• Submit pull requests with improvements
• Improve documentation or examples

Before contributing, please ensure your code follows Java + Spring Boot conventions.

📬 Contact & Hire Me

🚀 Want to add more advanced features to this project (PostgreSQL/NoSQL database, caching, message broker like "Kafka, Pub/Sub," etc.) I’ve got you covered! You can hire me.

Company or Startup? I can work full-time or part-time, 👉 Remote or On-site.

💌 Reach me at: hamzaelmarjani@gmail.com

✨ Thank you!

Support

If you like this project, consider supporting me on Patreon 💖

❤️ Thanks for reading, Happy Coding 💻