B2C E-commerce Multi-Vendor Backend

A comprehensive Spring Boot backend for a multi-vendor B2C e-commerce platform specializing in fresh produce and household essentials.

Features

• Multi-role Authentication: Customer, Vendor, and Admin roles with JWT
• Product Management: CRUD operations for products with vendor-specific access
• Order Management: Complete order lifecycle with status tracking
• Shopping Cart: Persistent cart with periodic cart functionality
• Price Quotes: OCR-powered quote system using Tesseract
• Reviews & Ratings: Product review system
• Shipping Addresses: Customer address management
• Admin Dashboard: User management and system analytics

Technology Stack

• Java 17
• Spring Boot 3.3.0
• Spring Security with JWT
• Spring Data JPA with Hibernate
• MySQL 8.0
• Flyway for database migrations
• Tesseract OCR for image text extraction
• Maven for dependency management

Prerequisites

• Java 17 or higher
• MySQL 8.0 or higher
• Maven 3.6+
• Tesseract OCR installed on your system

Setup Instructions

1. Database Setup

Create a MySQL database:

CREATE DATABASE b2c_ecommerce;

2. Configuration

Update src/main/resources/application.yml with your database credentials:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/b2c_ecommerce?useSSL=false&serverTimezone=UTC
    username: your_db_user
    password: your_db_password
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: true
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true

jwt:
  secret: your_jwt_secret_key_here
  expiration: 86400000

tesseract:
  datapath: /usr/share/tesseract-ocr/4.00/tessdata
  language: eng

3. Tesseract Installation

macOS:

brew install tesseract

Ubuntu/Debian:

sudo apt-get install tesseract-ocr

Windows: Download from https://github.com/UB-Mannheim/tesseract/wiki

4. Build and Run

# Navigate to project directory
cd b2c-ecommerce-backend

# Build the project
mvn clean install

# Run the application
mvn spring-boot:run

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

API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• GET /api/auth/profile - Get user profile

Products

• GET /api/products - Get all products (public)
• GET /api/products/{id} - Get product by ID (public)
• POST /api/products - Create product (vendor only)
• PUT /api/products/{id} - Update product (vendor only)
• DELETE /api/products/{id} - Delete product (vendor only)

Categories

• GET /api/admin/categories - Get all categories (admin only)
• POST /api/admin/categories - Create category (admin only)
• PUT /api/admin/categories/{id} - Update category (admin only)
• DELETE /api/admin/categories/{id} - Delete category (admin only)

Cart

• GET /api/cart - Get user cart (customer only)
• POST /api/cart/items - Add item to cart (customer only)
• PUT /api/cart/items/{id} - Update cart item (customer only)
• DELETE /api/cart/items/{id} - Remove cart item (customer only)
• POST /api/cart/checkout - Checkout cart (customer only)

Orders

• GET /api/orders - Get user orders (customer only)
• GET /api/orders/{id} - Get order by ID (customer only)
• GET /api/orders/vendor - Get vendor orders (vendor only)
• PUT /api/orders/{id}/status - Update order status (vendor only)

Price Quotes

• POST /api/quotes - Upload quote with OCR (customer only)
• GET /api/quotes - Get user quotes (customer only)
• GET /api/quotes/{id} - Get quote by ID (customer only)

Reviews

• GET /api/reviews/products/{productId} - Get product reviews (public)
• POST /api/reviews/products/{productId} - Create review (customer only)

Shipping Addresses

• GET /api/shipping-addresses - Get user addresses (customer only)
• POST /api/shipping-addresses - Create address (customer only)
• PUT /api/shipping-addresses/{id} - Update address (customer only)
• DELETE /api/shipping-addresses/{id} - Delete address (customer only)

Periodic Carts

• GET /api/periodic-carts - Get user periodic carts (customer only)
• POST /api/periodic-carts - Create periodic cart (customer only)
• PUT /api/periodic-carts/{id} - Update periodic cart (customer only)
• DELETE /api/periodic-carts/{id} - Delete periodic cart (customer only)

Admin

• GET /api/admin/users - Get all users (admin only)
• POST /api/admin/users/{id}/verify - Verify vendor (admin only)
• DELETE /api/admin/users/{id} - Delete user (admin only)
• GET /api/admin/reports/system - Get system reports (admin only)

Default Admin User

After running the migrations, a default admin user is created:

• Email: admin@freshgrocer.com
• Password: password

Testing the API

1. Register a Customer

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "password": "password123",
    "role": "CUSTOMER",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "1234567890"
  }'

2. Login

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

3. Use the JWT Token

curl -X GET http://localhost:8080/api/products \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Database Schema

The application uses the following main entities:

• Users: Authentication and role management
• Customers: Customer-specific information
• Vendors: Vendor-specific information
• Products: Product catalog with vendor association
• Categories: Product categorization
• Orders: Order management
• Carts: Shopping cart functionality
• Reviews: Product reviews and ratings
• Price Quotes: OCR-powered quote system
• Shipping Addresses: Customer address management
• Periodic Carts: Scheduled cart functionality

Security

• JWT-based authentication
• Role-based access control (CUSTOMER, VENDOR, ADMIN)
• BCrypt password encoding
• CORS configuration
• Input validation and sanitization

Error Handling

The application includes comprehensive error handling:

• Global exception handler
• Proper HTTP status codes
• Structured error responses
• Validation errors

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.