Documentation

Getting Started

STSTSI Commerce is an enterprise-grade, self-hosted e-commerce platform built with Java 21 and Spring Boot 3. This documentation will guide you through installation, configuration, and deployment of the platform.

System Requirements

Prerequisites

• Java 21 or higher - Latest LTS version required
• Maven 3.8+ - Build tool
• PostgreSQL 12+ - Primary database
• RabbitMQ - Optional, for asynchronous messaging
• Docker - Optional, for containerized deployment

Minimum Server Specifications

• RAM: 4GB minimum, 8GB+ recommended for production
• CPU: 2 cores minimum, 4+ cores recommended
• Storage: 20GB minimum, SSD recommended
• OS: Linux, Windows, or macOS

Installation

1. Database Setup

Create a PostgreSQL database and user:

CREATE DATABASE marketing_db;
CREATE USER marketing_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE marketing_db TO marketing_user;

2. Clone and Build

git clone https://github.com/your-org/ststsi-commerce.git
cd ststsi-commerce
mvn clean install

3. Configure Environment

Copy the example environment file and configure:

cp .env.example .env

Edit .env with your configuration (see Configuration section).

Configuration

Required Environment Variables

DATABASE_URL=jdbc:postgresql://localhost:5432/marketing_db
DATABASE_USERNAME=marketing_user
DATABASE_PASSWORD=your_secure_password
REMEMBER_ME_SECRET=your_32_character_random_string
JWT_SECRET=your_256_bit_secret_key

Optional Configuration

CORS_ALLOWED_ORIGINS=http://localhost:3000,https://yourapp.com
PAYMENT_MOCK_ENABLED=true
RABBITMQ_ENABLED=true
RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672
RABBITMQ_USERNAME=guest
RABBITMQ_PASSWORD=guest

Application Ports

• Storefront API: 8082 - REST API for customer-facing applications
• Manager Admin: 8080 - Administrative web interface

API Reference

HATEOAS REST API

The Storefront API follows HATEOAS (Hypermedia as the Engine of Application State) principles, providing a self-documenting, discoverable API at Level 3 of the Richardson Maturity Model.

API Root

GET http://localhost:8082/api

Returns links to all available resources with HAL+JSON format.

Authentication

Products

Shopping Cart

Orders

Platform Features

Product Management

• Multi-SKU products with variants (size, color, storage, etc.)
• Rich product catalog with categories and images
• Real-time inventory tracking with reservation system
• Product search and filtering

Shopping Experience

• Session-based carts for anonymous users
• Persistent carts for authenticated users
• Guest checkout without account creation
• Automatic cart merging on login
• Real-time price and promotion calculation

Promotions & Discounts

• Coupon codes with usage limits
• Automatic time-based promotions
• Price-based promotions (spend $X, get Y% off)
• Product-specific promotions
• Tax-free promotion variants

Order Management

• Complete order lifecycle (Pending → Confirmed → Shipped → Delivered)
• Guest order tracking
• Server-side price validation
• Automated inventory updates

Customer Features

• Account management with profiles
• Order history
• Product reviews and ratings
• Wishlist functionality
• Multiple shipping addresses

Admin Capabilities

• Role-based access control (ADMIN, PRODUCT_MANAGER, ORDER_MANAGER, etc.)
• Comprehensive product and inventory management
• Order processing and status updates
• Promotion and tax configuration
• Customer and sales analytics

Payment Integration

Supported Payment Providers

STSTSI Commerce uses a Service Provider Interface (SPI) pattern for extensible payment integration.

Stripe Integration

Configure Stripe payment processing:

1. Create a Stripe account at stripe.com
2. Obtain your API keys (publishable and secret)
3. Configure in Manager Admin → Payment Configuration
4. Enter your Stripe secret key and enable the provider

Mock Payments (Development)

For development and testing without a payment gateway:

PAYMENT_MOCK_ENABLED=true

Adding Custom Payment Providers

Implement the PaymentProvider interface and register via Java ServiceLoader:

public class MyPaymentProvider implements PaymentProvider {
    @Override
    public String getName() {
        return "my-provider";
    }

    @Override
    public PaymentResult processPayment(PaymentRequest request) {
        // Implementation
    }

    // ... other methods
}

Deployment

Running Locally

# Storefront API
mvn spring-boot:run -pl commerce-storefront-api

# Manager Admin
mvn spring-boot:run -pl commerce-manager

Docker Deployment

docker-compose up -d

Production Deployment

Recommended production setup:

• Use environment-specific configuration files
• Enable SSL/TLS certificates
• Configure proper CORS origins
• Use strong JWT and Remember-Me secrets
• Set up database backups
• Configure logging and monitoring
• Use a reverse proxy (Nginx, Apache) for load balancing

Database Migrations

The platform uses Liquibase for database migrations. Migrations run automatically on startup. In production, consider running migrations manually before deployment.