🛒 E-Commerce Backend

A production-ready RESTful API for an e-commerce platform built with Spring Boot 3, following Modular Monolith architecture with Port & Adapter pattern — designed for easy migration to microservices.

---

📋 Table of Contents

• Tech Stack
• Architecture
• Modules
• Features
• Getting Started
• API Documentation
• Testing
• Project Structure

---

🛠 Tech Stack

Category	Technology
Framework	Spring Boot 3.5, Spring Security, Spring Data JPA
Language	Java 21
Database	PostgreSQL 16
Cache	Redis 7
Authentication	JWT (Access + Refresh Token)
Payment	VNPay
Image Upload	Cloudinary
Email	JavaMailSender + MailHog (dev)
Real-time	Server-Sent Events (SSE)
Documentation	Swagger / OpenAPI 3
Testing	JUnit 5, Testcontainers, k6
Build	Maven

---

🏗 Architecture

Modular Monolith + Port & Adapter

The application is structured as a Modular Monolith — each business domain is an independent module with clear boundaries, communicating through defined interfaces (Ports).

┌─────────────────────────────────────────────┐
│                  API Layer                  │
│         (Controllers + Swagger)             │
├──────────┬──────────┬───────────┬───────────┤
│  User    │  Catalog │   Order   │  Payment  │
│  Module  │  Module  │   Module  │  Module   │
├──────────┴──────────┴───────────┴───────────┤
│              Port & Adapter                 │
│    (Inter-module communication via          │
│     interfaces, not direct calls)           │
├─────────────────────────────────────────────┤
│           Spring Event Bus                  │
│   (Async: OrderCreated → ReserveStock)      │
├──────────────────┬──────────────────────────┤
│   PostgreSQL     │    Redis Cache            │
└──────────────────┴──────────────────────────┘

Key Design Decisions

• Port & Adapter — modules communicate through interfaces, never direct class calls
• Spring Events — async domain events replace tight coupling (e.g., OrderCreatedEvent → Inventory reserves stock)
• Optimistic Locking — prevents overselling without pessimistic locks
• Idempotency Keys — duplicate order requests are safely ignored
• Snapshot Pattern — order items store price/name at time of purchase

Why Modular Monolith?

Each module follows the same internal structure as a microservice:

Handler (Event) → Service → Port Interface
Controller (HTTP) → Service → Port Interface

Migrating to microservices only requires:

• Replacing @EventListener with @KafkaListener
• Replacing Port JPA implementations with Feign Clients
• No changes to Service or Handler layer

---

📦 Modules

Module	Responsibility
user	Auth (JWT), profile, address, wishlist
catalog	Products, categories, variants, image upload
inventory	Stock management, optimistic locking
order	Cart, order lifecycle, vouchers
payment	COD & VNPay integration
review	Product reviews & ratings
notification	Real-time SSE + email notifications

---

✨ Features

Authentication & User

• Register / Login with JWT (Access + Refresh Token)
• Refresh token rotation — old token revoked on refresh
• Logout — revokes refresh token
• Change password — revokes all sessions
• Forgot password — email with reset link (15-min expiry via Redis)
• Reset password
• User profile management
• Multiple shipping addresses

Catalog

• Product listing with filtering & pagination
• Category management
• Product variants (size, color, etc.)
• Image upload via Cloudinary

Inventory

• Real-time stock tracking
• Optimistic Locking — concurrent purchase protection
• Reserve → Commit / Release flow

Order & Cart

• Persistent cart (1 cart per user)
• Place order from cart
• Voucher / discount codes
• Dynamic shipping fee calculation
• Order status history (full audit trail)
• Order cancellation
• Auto-cancel on payment timeout (15 minutes)

Payment

• COD — auto-confirms order immediately
• VNPay — redirect flow with callback verification
• Idempotency — duplicate payments safely rejected
• Payment event audit log

Notification

• Real-time SSE — instant order status push to browser
• Email — order status change notifications
• MailHog for local email testing

Admin

• User management (ban/unban)
• Product & category CRUD
• Inventory management
• Order management & status updates
• Voucher management
• Sales dashboard

---

🚀 Getting Started

Prerequisites

• Java 21+
• Maven 3.9+
• Docker & Docker Compose

1. Clone & Start Infrastructure

git clone https://github.com/Tran-Nguyen-26/ecommerce.git
cd ecommerce

# Start PostgreSQL, Redis, MailHog
docker-compose up -d

2. Configure Environment

Copy and update environment variables (or use defaults for local dev):

# application.yml defaults work out of the box for local dev
# PostgreSQL: localhost:5433
# Redis:      localhost:6380
# MailHog:    localhost:1025 (SMTP), localhost:8025 (UI)

3. Run Application

./mvnw spring-boot:run

4. Verify

Service	URL
API	http://localhost:8080
Swagger UI	http://localhost:8080/swagger-ui.html
MailHog UI	http://localhost:8025
Health Check	http://localhost:8080/actuator/health

---

📖 API Documentation

Full API docs available at http://localhost:8080/swagger-ui.html

📁 Project Structure

src/main/java/com/ttn/ecommerce/
├── infrastructure/
│   ├── config/          # Security, CORS, Swagger
│   └── email/           # EmailService
├── modules/
│   ├── catalog/
│   │   ├── api/         # Controllers
│   │   ├── application/ # Services, DTOs, Ports
│   │   ├── domain/      # Entities
│   │   └── infrastructure/ # JPA Repositories, Port impls
│   ├── inventory/
│   ├── notification/
│   ├── order/
│   ├── payment/
│   ├── review/
│   └── user/
└── shared/
    ├── event/           # Domain events + EventPublisherPort
    ├── exception/       # GlobalExceptionHandler, ErrorCode
    └── response/        # ApiResponse wrapper

---

🐳 Docker Services

Service	Container	Port
PostgreSQL	ecommerce-db	5433:5432
Redis	ecommerce-redis	6380:6379
MailHog	ecommerce-mail	1025 (SMTP), 8025 (UI)

---

📝 License

MIT