ShopNex — Production-Style E-Commerce REST API

A fully-featured, production-style e-commerce backend built with Spring Boot 3, Spring Security + JWT, and H2 in-memory database. Designed with clean architecture, role-based access control, and real-world business logic.

---

📦 Tech Stack

Layer	Technology
Framework	Spring Boot 3.2.5
Security	Spring Security + JJWT 0.11.5
Persistence	Spring Data JPA + H2 (in-memory)
Validation	Jakarta Bean Validation (@Valid)
DTO Mapping	ModelMapper 3.2.0
Build Tool	Maven
Boilerplate	Lombok
Language	Java 17

---

🗂️ Project Structure

src/main/java/com/shopnex/
├── ShopNexApplication.java
├── config/
│   ├── AppConfig.java          # ModelMapper, BCrypt, AuthManager beans
│   ├── SecurityConfig.java     # JWT filter chain, role-based URL rules
│   └── DataSeeder.java         # Sample data loader (runs at startup)
├── controller/
│   ├── AuthController.java
│   ├── CategoryController.java
│   ├── ProductController.java
│   ├── CartController.java
│   ├── OrderController.java
│   └── AdminController.java
├── service/
│   ├── AuthService.java
│   ├── CategoryService.java
│   ├── ProductService.java
│   ├── CartService.java
│   ├── OrderService.java
│   └── serviceImpl/
│       ├── AuthServiceImpl.java
│       ├── CategoryServiceImpl.java
│       ├── ProductServiceImpl.java
│       ├── CartServiceImpl.java
│       └── OrderServiceImpl.java
├── repository/
│   ├── UserRepository.java
│   ├── CategoryRepository.java
│   ├── ProductRepository.java
│   ├── CartRepository.java
│   ├── CartItemRepository.java
│   └── OrderRepository.java
├── model/entity/
│   ├── User.java
│   ├── Category.java
│   ├── Product.java
│   ├── Cart.java
│   ├── CartItem.java
│   ├── Order.java
│   ├── OrderItem.java
│   ├── Role.java               # Enum: CUSTOMER, ADMIN
│   └── OrderStatus.java        # Enum: PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED
├── dto/
│   ├── request/
│   │   ├── RegisterRequest.java
│   │   ├── LoginRequest.java
│   │   ├── CategoryRequest.java
│   │   ├── ProductRequest.java
│   │   ├── CartItemRequest.java
│   │   └── OrderStatusUpdateRequest.java
│   └── response/
│       ├── AuthResponse.java
│       ├── UserResponse.java
│       ├── CategoryResponse.java
│       ├── ProductResponse.java
│       ├── CartItemResponse.java
│       ├── CartResponse.java
│       ├── OrderItemResponse.java
│       └── OrderResponse.java
├── security/
│   ├── JwtTokenProvider.java
│   ├── JwtAuthenticationFilter.java
│   └── CustomUserDetailsService.java
└── exception/
    ├── ResourceNotFoundException.java
    ├── BadRequestException.java
    ├── UnauthorizedException.java
    ├── ApiError.java
    └── GlobalExceptionHandler.java

---

🚀 Setup & Run

Prerequisites

• Java 17+
• Maven 3.8+

Steps

# 1. Clone / navigate to project directory
cd E-Commerce

# 2. Build the project
mvn clean install

# 3. Run the application
mvn spring-boot:run

The API will start at: http://localhost:8080
H2 Console (dev only): http://localhost:8080/h2-console

• JDBC URL: jdbc:h2:mem:shopnexdb
• Username: sa | Password: (empty)

---

👤 Pre-loaded Sample Data

Role	Email	Password
ADMIN	admin@shopnex.com	admin123
CUSTOMER	john@shopnex.com	john123

3 Categories: Electronics, Clothing, Books
10 Products: 4 Electronics, 3 Clothing, 3 Books

---

🔑 JWT Authentication — Sample Usage

Step 1 — Login and get token

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"john@shopnex.com","password":"john123"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "tokenType": "Bearer",
  "userId": 2,
  "name": "John Doe",
  "email": "john@shopnex.com",
  "role": "CUSTOMER"
}

Step 2 — Use token in requests

curl http://localhost:8080/api/cart \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

---

📋 Full API Endpoint Table

🔓 Auth — Public

Method	Endpoint	Description	Auth Required
POST	/api/auth/register	Register new customer	❌ No
POST	/api/auth/login	Login and receive JWT	❌ No

---

📂 Categories

Method	Endpoint	Description	Auth Required
GET	/api/categories	List all categories	❌ No
GET	/api/categories/{id}	Get category by ID	❌ No
POST	/api/categories	Create category	✅ ADMIN
PUT	/api/categories/{id}	Update category	✅ ADMIN
DELETE	/api/categories/{id}	Delete category	✅ ADMIN

---

🛍️ Products

Method	Endpoint	Description	Auth Required
GET	/api/products	Paginated product list (+ filters)	❌ No
GET	/api/products/{id}	Get product by ID	❌ No
POST	/api/products	Create product	✅ ADMIN
PUT	/api/products/{id}	Update product	✅ ADMIN
DELETE	/api/products/{id}	Delete product	✅ ADMIN

Product Listing Query Parameters

Parameter	Type	Default	Description
page	int	0	Zero-based page index
size	int	10	Number of items per page
sortBy	string	id	Field to sort by (e.g., price)
sortDir	string	asc	Sort direction: asc or desc
categoryId	Long	—	Filter by category ID
keyword	string	—	Search by product name

Example:

GET /api/products?page=0&size=5&sortBy=price&sortDir=asc&categoryId=1

---

🛒 Cart — Requires Authentication (CUSTOMER)

Method	Endpoint	Description	Auth Required
GET	/api/cart	View cart with grand total	✅ CUSTOMER
POST	/api/cart/items	Add item to cart	✅ CUSTOMER
PUT	/api/cart/items/{itemId}	Update item quantity	✅ CUSTOMER
DELETE	/api/cart/items/{itemId}	Remove item from cart	✅ CUSTOMER

Add to cart body:

{
  "productId": 3,
  "quantity": 2
}

---

📦 Orders — Requires Authentication (CUSTOMER)

Method	Endpoint	Description	Auth Required
POST	/api/orders	Place order from cart	✅ CUSTOMER
GET	/api/orders	View my order history	✅ CUSTOMER
GET	/api/orders/{id}	View specific order (own only)	✅ CUSTOMER

---

🔧 Admin Panel — Requires ADMIN Role

Method	Endpoint	Description
POST	/api/admin/products	Create product
PUT	/api/admin/products/{id}	Update product
DELETE	/api/admin/products/{id}	Delete product
GET	/api/admin/orders	View all orders (paginated)
GET	/api/admin/orders/{id}	View any order by ID
PATCH	/api/admin/orders/{id}/status	Update order status

Update order status body:

{
  "status": "CONFIRMED"
}

Valid statuses: PENDING → CONFIRMED → SHIPPED → DELIVERED | CANCELLED

---

⚠️ Error Response Format

All errors return a consistent JSON structure:

{
  "status": 400,
  "error": "VALIDATION_FAILED",
  "message": "Input validation failed. Please check field errors.",
  "timestamp": "2024-01-15T10:30:00",
  "fieldErrors": {
    "email": "Email must be a valid email address",
    "password": "Password must be at least 6 characters"
  }
}

---

🔐 Role-Based Access Summary

Feature	CUSTOMER	ADMIN
Register / Login	✅	✅
Browse products/categories	✅	✅
Manage cart	✅	❌
Place/view own orders	✅	❌
Manage products	❌	✅
Manage categories	❌	✅
View all orders	❌	✅
Update order status	❌	✅

---

🗃️ Database Schema Overview

users           → id, name, email, password, role
categories      → id, name, description
products        → id, name, description, price, stock_quantity, image_url, category_id
carts           → id, user_id
cart_items      → id, cart_id, product_id, quantity
orders          → id, user_id, total_amount, status, created_at, updated_at
order_items     → id, order_id, product_id, quantity, price_at_purchase

---

📝 Notes

• JWT tokens expire in 24 hours (configurable via shopnex.jwt.expiration-ms)
• H2 database is reset on every restart — data is re-seeded automatically
• Passwords are hashed with BCrypt
• Price history is snapshotted at order time — future product price changes don't affect past orders
• Cart is automatically cleared after a successful order placement