spring-store

A Spring Boot–based demo application that models a simple online store.
It focuses on persistence with Spring Data JPA, entity relationships, pagination, sorting, and database migrations with Flyway.

---

Table of Contents

• Overview
• Features
• Tech Stack
• Architecture & Domain Model
• Getting Started
  • Prerequisites
  • Database Configuration
  • Running the Application
• Database Migrations
• Useful Maven Commands
• Running Tests
• Project Structure
• Extending the Project
• License

---

Overview

This project is a learning- and demo-oriented Spring Boot application for a store domain.
It showcases:

• How to model entities and relationships with JPA/Hibernate.
• How to use Spring Data JPA repositories, query methods, JPQL, specifications, and the Criteria API.
• How to manage schema evolution using Flyway migrations.
• Basic pagination, sorting, and DTO/projection patterns.

The application currently starts a Spring Boot context, executes some data-access/service logic, and prints results to the console. It can be extended with REST APIs or a UI layer as needed.

---

Features

Domain & Data Access

• User management with:
  • One-to-many addresses
  • One-to-one profile (with loyalty points and other metadata)
  • Many-to-many tags
  • Wishlist / favorite products (many-to-many with products)
• Product catalog:
  • Products belonging to categories
  • Price and description fields
• Category and tag management

Spring Data JPA usage

• Standard CRUD repositories (CrudRepository, JpaRepository)
• Derived query methods (e.g., finding products by name, price range, etc.)
• Paging and sorting with PageRequest and Sort
• DTO-based queries and interface-based projections
• Specifications (Specification<T>) for dynamic filtering
• Custom repository implementation using the JPA Criteria API
• Stored procedure invocation via Spring Data JPA

Database & Migrations

• MySQL backing database
• Flyway-based schema migrations:
  • Initial user/address schema
  • Moving columns between tables
  • Profiles, tags, categories, products, wishlist, and stored procedure creation

---

Tech Stack

• Language: Java 23
• Framework: Spring Boot 3.4.x
• Persistence:
  • Spring Data JPA
  • Hibernate (via Spring Boot)
  • JPA Criteria API & Specifications
• Database: MySQL
• Migrations: Flyway (core + MySQL)
• Build Tool: Maven (with Maven Wrapper)
• Utilities: Lombok

---

Architecture & Domain Model

The core package is:

• com.codewithmosh.store

Key concepts:

• Entities: User, Address, Profile, Tag, Category, Product
• Relationships:
  • User ↔ Address: one-to-many, with cascading and orphan removal
  • User ↔ Profile: one-to-one, sharing primary key
  • User ↔ Tag: many-to-many via a join table
  • User ↔ Product (wishlist): many-to-many via wishlist table
  • Product ↔ Category: many-to-one

The UserService class demonstrates common service-layer operations such as fetching, pagination, dynamic queries, and updates.

---

Getting Started

Prerequisites

• Java: JDK 23 installed and on your PATH
• Maven: Not required explicitly if you use the Maven Wrapper (mvnw / mvnw.cmd), but Maven 3.9+ is recommended.
• Database: A running MySQL instance (local or remote)

Database Configuration

Default configuration is defined in application.yaml:

• URL: jdbc:mysql://localhost:3306/store?createDatabaseIfNotExist=true
• Username: root
• Password: MyPassword!

To adjust for your environment, edit:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/store?createDatabaseIfNotExist=true
    username: root
    password: MyPassword!
  jpa:
    show-sql: true

Important:
Update username and password to match your local MySQL credentials.
The database (store) will be created automatically if it doesn’t exist (as per the URL).

Running the Application

From the project root:

Using Maven Wrapper (recommended):

./mvnw spring-boot:run

On Windows:

mvnw.cmd spring-boot:run

Or using a locally installed Maven:

mvn spring-boot:run

Once started, Spring Boot will:

1. Connect to MySQL.
2. Run Flyway migrations to set up or update the schema.
3. Start the application, execute the main logic in StoreApplication, and log output to the console.

---

Database Migrations

Flyway is used to manage database schema evolution. Migration scripts are located under:

• src/main/resources/db/migration/

They are named following Flyway’s V<version>__<description>.sql convention and include:

• Initial creation of users and addresses
• Adding and moving columns
• Creating profiles, tags, user_tags, categories, products, and wishlist
• Adding a stored procedure (findProductsByPrice)

To run Flyway migrations via Maven:

./mvnw flyway:migrate

To clean and reinitialize the schema (use with care, it drops objects):

./mvnw flyway:clean flyway:migrate

---

Useful Maven Commands

Compile:

./mvnw compile

Run the application:

./mvnw spring-boot:run

Run tests:

./mvnw test

Package as a runnable JAR:

./mvnw clean package

The packaged JAR will be available under target/. Run it with:

java -jar target/store-0.0.1-SNAPSHOT.jar

---

Running Tests

To run the test suite:

./mvnw test

By default, tests focus on verifying that the Spring context loads correctly.
You can extend the tests to cover repositories, services, and integration scenarios as you evolve the project.

---

Project Structure

High-level layout:

spring-store/
  ├─ src/
  │  ├─ main/
  │  │  ├─ java/com/codewithmosh/store/
  │  │  │  ├─ entities/        # JPA entity classes
  │  │  │  ├─ repositories/    # Spring Data repositories & specs
  │  │  │  ├─ dtos/            # DTOs and projections
  │  │  │  ├─ services/        # Service-layer logic
  │  │  │  └─ StoreApplication # Spring Boot entry point
  │  │  └─ resources/
  │  │     ├─ db/migration/    # Flyway migration scripts
  │  │     ├─ static/          # Static resources (e.g., index.html)
  │  │     └─ application.yaml # Spring configuration
  │  └─ test/
  │     └─ java/com/codewithmosh/store/ # Tests
  ├─ pom.xml                    # Maven configuration
  └─ README.md                  # This file

---

Extending the Project

Some possible next steps if you want to build on this foundation:

• REST API: Add Spring MVC controllers to expose endpoints for users, products, categories, and tags.
• Validation & DTOs: Introduce API-specific DTOs and bean validation for input.
• Security: Add Spring Security for authentication and authorization.
• Caching: Use Spring Cache to improve performance for frequently requested data.
• Front-End: Build a front-end (e.g., React, Angular, or Thymeleaf) to consume the APIs.

---

License

This project is provided for educational and demonstrational purposes.
Add your preferred license information here (e.g., MIT, Apache 2.0) if you intend to publish or share it.