A production-ready, scalable e-commerce platform built with Spring Boot microservices architecture, featuring user authentication (JWT + OAuth2), product catalog management with Redis caching, Stripe payment integration, and asynchronous email notifications via Kafka.

• System Architecture
• Features
• Technology Stack
• Prerequisites
• Quick Start
• Detailed Setup
• API Endpoints
• Testing the Application
• Configuration
• Troubleshooting
• Project Structure
• Contributing
• License

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#6366f1','primaryTextColor':'#fff','primaryBorderColor':'#4f46e5','lineColor':'#6366f1','secondaryColor':'#22c55e','tertiaryColor':'#f59e0b','background':'#ffffff','mainBkg':'#f3f4f6','secondBkg':'#e5e7eb','tertiaryBkg':'#d1d5db','textColor':'#1f2937','fontSize':'16px','fontFamily':'Inter, system-ui, sans-serif'}}}%%
graph TB
    Client([👤 Client/Browser]):::clientStyle
    
    subgraph EntryLayer["🌐 Entry Layer"]
        Gateway[API Gateway<br/>📍 Port: 3001<br/>🔐 JWT Validation]:::gatewayStyle
        Discovery[Service Discovery<br/>📍 Port: 8761<br/>📡 Eureka Server]:::discoveryStyle
    end
    
    subgraph BusinessLayer["⚙️ Business Services Layer"]
        UserService[User Service<br/>📍 Port: 8080<br/>🔐 Auth & JWT]:::serviceStyle
        ProductService[Product Service<br/>📍 Port: 8081<br/>🛍️ Catalog]:::serviceStyle
        PaymentService[Payment Service<br/>📍 Port: 8082<br/>💳 Payments]:::serviceStyle
        EmailService[Email Service<br/>📍 Port: 8181<br/>📧 Notifications]:::serviceStyle
    end
    
    subgraph DataLayer["💾 Data Layer"]
        PostgreSQL[(PostgreSQL<br/>Users DB)]:::dbStyle
        MySQL[(MySQL<br/>Products DB)]:::dbStyle
        Redis[(Redis<br/>Cache)]:::cacheStyle
    end
    
    subgraph MessageLayer["📨 Message Queue"]
        Kafka[Kafka Broker<br/>📍 Port: 9092]:::messageStyle
        Zookeeper[Zookeeper<br/>📍 Port: 2181]:::messageStyle
    end
    
    subgraph ExternalLayer["🌍 External Services"]
        Google[Google OAuth2<br/>🔑 Authentication]:::externalStyle
        Stripe[Stripe API<br/>💰 Payments]:::externalStyle
        Gmail[Gmail SMTP<br/>✉️ Email Delivery]:::externalStyle
    end
    
    Client ==>|All API Requests| Gateway
    Gateway -.->|Service Lookup| Discovery
    
    Gateway ==>|/api/auth/**<br/>/api/user/**| UserService
    Gateway ==>|/api/products/**<br/>/api/categories/**| ProductService
    Gateway ==>|/api/payments/**| PaymentService
    
    UserService ==>|Store/Retrieve Users| PostgreSQL
    ProductService ==>|CRUD Operations| MySQL
    ProductService <-->|Cache Queries| Redis
    
    UserService -->|Publish Events| Kafka
    Kafka -->|Consume Events| EmailService
    Kafka -.->|Coordination| Zookeeper
    
    UserService -.->|OAuth2 Login| Google
    PaymentService -.->|Process Payments| Stripe
    EmailService -.->|Send Emails| Gmail
    
    UserService -.->|Register Service| Discovery
    ProductService -.->|Register Service| Discovery
    PaymentService -.->|Register Service| Discovery
    EmailService -.->|Register Service| Discovery
    
    classDef clientStyle fill:#6366f1,stroke:#4f46e5,stroke-width:3px,color:#fff
    classDef gatewayStyle fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
    classDef discoveryStyle fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
    classDef serviceStyle fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
    classDef dbStyle fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
    classDef cacheStyle fill:#ec4899,stroke:#db2777,stroke-width:2px,color:#fff
    classDef messageStyle fill:#14b8a6,stroke:#0d9488,stroke-width:2px,color:#fff
    classDef externalStyle fill:#64748b,stroke:#475569,stroke-width:2px,color:#fff

• JWT Authentication with RSA-256 signing
• OAuth2 Integration with Google Sign-In
• Multi-Authentication Support (Local + OAuth2)
• Role-Based Access Control (ADMIN, USER)
• Password Security with BCrypt hashing
• Token Expiration (1 hour by default)

• Full CRUD Operations for products and categories
• Redis Caching with 1-hour TTL for performance
• Soft Delete pattern for data retention
• Pagination & Sorting for efficient data retrieval
• Category Management with automatic creation
• Input Validation with custom constraints
• Flyway Migrations for database versioning

• Stripe Integration for secure payments
• Payment Link Generation with custom callbacks
• Multi-Gateway Support (Stripe active, Razorpay ready)
• Success/Failure Callbacks for order confirmation
• Extensible Gateway Interface for future integrations

• Kafka-Based Async Processing for scalability
• Gmail SMTP Integration with TLS
• Welcome Emails on user registration
• Customizable Templates for different events
• Retry Mechanism via Kafka consumer groups

• Centralized Routing to all microservices
• JWT Token Validation before forwarding requests
• Public Endpoint Exemptions for auth and product browsing
• Load Balancing via Eureka integration
• Request/Response Logging capabilities

• Automatic Service Registration on startup
• Health Monitoring of all services
• Client-Side Load Balancing for resilience
• Eureka Dashboard for service visualization
• Dynamic Service Location without hard-coded URLs

• Java 17 - Programming language
• Spring Boot 3.5.x - Application framework
• Spring Cloud - Microservices infrastructure
  • Spring Cloud Gateway - API Gateway
  • Netflix Eureka - Service Discovery
• Spring Security - Authentication & Authorization
• Spring Data JPA - Data persistence
• Hibernate - ORM framework

• PostgreSQL 15 - User service database
• MySQL 8.0 - Product service database
• Redis - Caching layer

• Apache Kafka 7.4.0 - Event streaming
• Apache Zookeeper 7.4.0 - Kafka coordination

• JWT (JSON Web Tokens) - Stateless authentication
• OAuth2 - Third-party authentication
• BCrypt - Password hashing
• RSA-256 - JWT signing algorithm

• Stripe API - Payment processing
• Google OAuth2 API - Social login
• Gmail SMTP - Email delivery

• Docker - Containerization
• Docker Compose - Multi-container orchestration
• Maven - Dependency management & build tool
• Flyway - Database migration tool

Before you begin, ensure you have the following installed:

• Docker (20.10+) and Docker Compose (2.0+)
• Java 17 (for local development without Docker)
• Maven 3.9+ (for local development)
• Git (for cloning the repository)

You'll need to create accounts and obtain API keys from:

1. Google Cloud Console - For OAuth2 credentials
2. Stripe - For payment processing API key
3. Gmail - For SMTP email sending (App Password required)

git clone https://github.com/yourusername/ecommerce-microservices.git
cd ecommerce-microservices

Create a .env file in the project root:

# Copy the example file
cp .env.example .env

Edit .env and add your credentials:

# Google OAuth2 Credentials
GOOGLE_CLIENT_ID=your-google-client-id-here
GOOGLE_CLIENT_SECRET=your-google-client-secret-here

# Stripe API Key
STRIPE_KEY=sk_test_your-stripe-test-key-here

# Gmail SMTP Credentials
SENDER_EMAIL=your-email@gmail.com
SENDER_PASSWORD=your-gmail-app-password-here

If you need to regenerate the keystore:

keytool -genkeypair -alias auth-server -keyalg RSA -keysize 2048 \
  -keystore user-service/src/main/resources/keystore.jks \
  -storepass password -validity 3650 \
  -dname "CN=Auth Server, OU=Development, O=ECommerce, L=City, ST=State, C=US"

# Copy to API Gateway
cp user-service/src/main/resources/keystore.jks api-gateway/src/main/resources/

# Build and start all services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f user-service

Wait for all services to start (approximately 2-3 minutes). You can check:

• Eureka Dashboard: http://localhost:8761
• API Gateway: http://localhost:3001
• User Service: http://localhost:8080
• Product Service: http://localhost:8081
• Payment Service: http://localhost:8082

# Health check
curl http://localhost:3001/api/test/check

# Get all products
curl http://localhost:3001/api/products/

# Get all categories
curl http://localhost:3001/api/categories/

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Navigate to APIs & Services > Credentials
4. Click Create Credentials > OAuth 2.0 Client ID
5. Configure consent screen if prompted
6. Select Web application as application type
7. Add authorized redirect URIs:

   http://localhost:8080/login/oauth2/code/google
   http://localhost:3001/login/oauth2/code/google
   

8. Copy Client ID and Client Secret to your .env file

1. Go to Stripe Dashboard
2. Create an account or sign in
3. Navigate to Developers > API Keys
4. Copy your Test Mode secret key (starts with sk_test_)
5. Add to .env file as STRIPE_KEY

Important: Never use production keys in development!

1. Enable 2-Factor Authentication on your Gmail account
2. Go to Google Account Settings
3. Navigate to Security > 2-Step Verification
4. Scroll down to App passwords
5. Generate a new app password for "Mail"
6. Copy the 16-character password (remove spaces)
7. Add to .env file as SENDER_PASSWORD

Security Note: Use app-specific passwords, never your actual Gmail password!

Each service needs an application.properties file. Examples are provided:

# User Service
cp user-service/application.properties.example user-service/src/main/resources/application.properties

# Product Service  
cp product-service/src/main/resources/templates/application-template.properties \
   product-service/src/main/resources/application.properties

# Email Service
cp email-service/application.properties.example \
   email-service/src/main/resources/application.properties

curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "password": "SecurePassword123!",
    "firstName": "John",
    "lastName": "Doe",
    "roles": ["USER"]
  }'

Expected Response:

{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "roles": ["USER"]
}

You should also receive a welcome email!

curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "password": "SecurePassword123!"
  }'

Expected Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "expires_in": 3600
}

Save the access_token for subsequent requests!

curl -X POST http://localhost:3001/api/products/ \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Awesome Laptop",
    "description": "High-performance laptop for developers",
    "price": 1299.99,
    "image": "https://example.com/laptop.jpg",
    "categoryTitle": "electronics"
  }'

# First call - hits database
curl http://localhost:3001/api/products/

# Second call - served from Redis cache
curl http://localhost:3001/api/products/

curl http://localhost:3001/api/user/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"

Expected Response:

{
  "userId": 1,
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "roles": ["ROLE_USER"]
}

curl -X POST http://localhost:3001/api/payments/initiatePayment/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"

Expected Response:

https://checkout.stripe.com/c/pay/cs_test_...

Open this URL in your browser to complete test payment.

curl "http://localhost:3001/api/products/list?pageNumber=0&pageSize=5&sortBy=price&ascending=false"

1. Open browser: http://localhost:3001/oauth2/authorization/google
2. Login with Google account
3. Authorize the application
4. You'll be redirected to success page with JWT token

First, create an admin user:

curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "AdminPassword123!",
    "firstName": "Admin",
    "lastName": "User",
    "roles": ["USER", "ADMIN"]
  }'

Login as admin and get all users:

curl http://localhost:3001/api/user/list \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN_HERE"

All services use environment variables for configuration:

Default ports (can be changed in application.properties):

# Infrastructure
Service Discovery: 8761
API Gateway: 3001
PostgreSQL: 5432
MySQL: 3306 (mapped to 3307 in Docker)
Redis: 6379
Kafka: 9092
Zookeeper: 2181

# Application Services
User Service: 8080
Product Service: 8081
Payment Service: 8082
Email Service: 8181

PostgreSQL (User Service):

spring.datasource.url=jdbc:postgresql://localhost:5432/authserver
spring.datasource.username=postgres
spring.datasource.password=root
spring.jpa.hibernate.ddl-auto=validate

MySQL (Product Service):

spring.datasource.url=jdbc:mysql://localhost:3306/productservice
spring.datasource.username=root
spring.datasource.password=password
spring.jpa.hibernate.ddl-auto=update

spring.data.redis.host=localhost
spring.data.redis.port=6379
spring.cache.type=redis

Cache Keys:

• Products: PRODUCTSSERVICE:product-list:all-products
• Individual Product: PRODUCTS:PRODUCT_{id}
• Categories: PRODUCTSSERVICE:category-list:all-categories
• Individual Category: CATEGORIES:CATEGORY_{id}

TTL: 1 hour (3600 seconds)

spring.kafka.bootstrap-servers=localhost:9092
spring.kafka.consumer.group-id=emailService

Topics:

• send-email - Email notification events

Problem: Docker containers fail to start

Solutions:

# Check Docker is running
docker --version
docker-compose --version

# Clean up and rebuild
docker-compose down -v
docker-compose up --build

# Check logs for specific service
docker-compose logs user-service

Problem: Could not connect to database

Solutions:

# Verify database is healthy
docker-compose ps

# Check database logs
docker-compose logs postgres-user
docker-compose logs mysql

# Restart database services
docker-compose restart postgres-user mysql

Problem: 401 Unauthorized or Invalid token

Solutions:

• Ensure keystore.jks exists in both user-service and api-gateway
• Verify keystore password matches in .env file
• Check token hasn't expired (1 hour validity)
• Ensure token is sent with Bearer prefix

# Regenerate keystore if needed
keytool -genkeypair -alias auth-server -keyalg RSA -keysize 2048 \
  -keystore keystore.jks -storepass password -validity 3650

Problem: Redirect URI mismatch

Solutions:

• Verify redirect URIs in Google Cloud Console match exactly:

  http://localhost:8080/login/oauth2/code/google
  

• Check GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env
• Ensure user-service is running on port 8080

Problem: Welcome email not received

Solutions:

• Verify Gmail App Password is correct (16 characters, no spaces)
• Check Kafka is running: docker-compose logs kafka
• Verify email-service logs: docker-compose logs email-service
• Ensure SENDER_EMAIL and SENDER_PASSWORD in .env

Problem: Payment link not generated

Solutions:

• Verify Stripe API key starts with sk_test_
• Check Stripe dashboard for API errors
• Ensure payment-service is running: docker-compose logs payment-service

Problem: Products always fetched from database

Solutions:

# Check Redis is running
docker-compose ps redis

# Connect to Redis CLI
docker exec -it my-product-service-redis redis-cli

# Check cached keys
KEYS *

# Clear cache if needed
FLUSHALL

Problem: Services not registering with Eureka

Solutions:

• Access Eureka dashboard: http://localhost:8761
• Verify eureka.client.serviceUrl.defaultZone in service configs
• Check service-discovery logs: docker-compose logs service-discovery
• Wait 30-60 seconds for services to register

Problem: Port already in use

Solutions:

# Find process using port (e.g., 8080)
lsof -i :8080  # macOS/Linux
netstat -ano | findstr :8080  # Windows

# Kill process or change port in application.properties

Problem: Compilation errors or dependency issues

Solutions:

# Clean Maven cache
mvn clean install -U

# Skip tests during build
mvn clean install -DskipTests

# Delete and recreate .m2 repository
rm -rf ~/.m2/repository
mvn clean install

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f user-service

# Last 100 lines
docker-compose logs --tail=100 product-service

# Since specific time
docker-compose logs --since 2024-01-01T10:00:00

---

## 📁 Project Structure

ecommerce-microservices/ │ ├── api-gateway/ # API Gateway Service │ ├── src/main/ │ │ ├── java/ │ │ │ └── com/john/personal/api_gateway/ │ │ │ ├── configuration/ │ │ │ │ ├── FilterConfig.java │ │ │ │ └── GatewayConfig.java │ │ │ └── security/ │ │ │ └── AuthenticationPreFilter.java │ │ └── resources/ │ │ ├── application.properties │ │ └── keystore.jks │ ├── Dockerfile │ └── pom.xml │ ├── service-discovery/ # Eureka Server │ ├── src/main/ │ │ ├── java/ │ │ │ └── org/john/personal/service_discovery/ │ │ │ └── ServiceDiscoveryApplication.java │ │ └── resources/ │ │ └── application.properties │ ├── Dockerfile │ └── pom.xml │ ├── user-service/ # User & Auth Service │ ├── src/main/ │ │ ├── java/ │ │ │ └── org/john/personal/userservice/ │ │ │ ├── config/ │ │ │ │ ├── JwtUserPrincipal.java │ │ │ │ └── SecurityConfig.java │ │ │ ├── controllers/ │ │ │ │ ├── AuthController.java │ │ │ │ ├── UserController.java │ │ │ │ └── OAuth2Controller.java │ │ │ ├── dtos/ │ │ │ │ ├── request/ │ │ │ │ │ ├── LoginRequestDto.java │ │ │ │ │ └── RegisterRequestDto.java │ │ │ │ └── response/ │ │ │ │ └── UserResponseDTO.java │ │ │ ├── models/ │ │ │ │ ├── UserEntity.java │ │ │ │ ├── Role.java │ │ │ │ ├── AuthProvider.java │ │ │ │ └── UserAuthMethodEntity.java │ │ │ ├── repositories/ │ │ │ │ ├── UserRepository.java │ │ │ │ └── UserAuthMethodRepository.java │ │ │ ├── security/ │ │ │ │ ├── JwtAuthenticationFilter.java │ │ │ │ └── OAuth2AuthenticationSuccessHandler.java │ │ │ └── services/ │ │ │ ├── UserServiceImpl.java │ │ │ ├── CustomUserDetailsService.java │ │ │ └── JwtService.java │ │ └── resources/ │ │ ├── application.properties │ │ ├── keystore.jks │ │ └── db/migration/ │ │ ├── V1__initial_schema.sql │ │ ├── V2__add_user_roles_table.sql │ │ ├── V3__change_username_to_email.sql │ │ ├── V4__add_oauth2_fields.sql │ │ ├── V5__.sql │ │ └── V6__password_set_null.sql │ ├── Dockerfile │ └── pom.xml │ ├── product-service/ # Product Catalog Service │ ├── src/main/ │ │ ├── java/ │ │ │ └── org/john/personal/productservice/ │ │ │ ├── configurations/ │ │ │ │ └── ApplicationConfig.java │ │ │ ├── controller/ │ │ │ │ ├── ProductController.java │ │ │ │ └── CategoryController.java │ │ │ ├── dto/ │ │ │ │ ├── ProductRequestDTO.java │ │ │ │ ├── ProductResponseDTO.java │ │ │ │ ├── CategoryRequestDTO.java │ │ │ │ └── CategoryResponseDTO.java │ │ │ ├── model/ │ │ │ │ ├── BaseModel.java │ │ │ │ ├── Product.java │ │ │ │ └── Category.java │ │ │ ├── repository/ │ │ │ │ ├── ProductRepo.java │ │ │ │ └── CategoryRepo.java │ │ │ ├── service/ │ │ │ │ ├── ProductService.java │ │ │ │ ├── ProductServiceImpl.java │ │ │ │ ├── CategoryService.java │ │ │ │ └── CategoryServiceImpl.java │ │ │ └── mapper/ │ │ │ ├── ProductMapper.java │ │ │ └── CategoryMapper.java │ │ └── resources/ │ │ ├── application.properties │ │ └── db/migration/ │ │ └── V1__init.sql │ ├── Dockerfile │ └── pom.xml │ ├── payment-service/ # Payment Processing Service │ ├── src/main/ │ │ ├── java/ │ │ │ └── org/john/personal/paymentservice/ │ │ │ ├── controllers/ │ │ │ │ └── PaymentController.java │ │ │ ├── paymentgateways/ │ │ │ │ ├── PaymentGateway.java │ │ │ │ ├── StripePaymentGateway.java │ │ │ │ └── RazorpayPaymentGateway.java │ │ │ └── services/ │ │ │ └── PaymentService.java │ │ └── resources/ │ │ └── application.properties │ ├── Dockerfile │ └── pom.xml │ ├── email-service/ # Email Notification Service │ ├── src/main/ │ │ ├── java/ │ │ │ └── org/john/personal/email_service/ │ │ │ ├── consumers/ │ │ │ │ └── SendEmailEventConsumer.java │ │ │ ├── dto/ │ │ │ │ └── SendEmailDto.java │ │ │ └── utils/ │ │ │ └── EmailUtil.java │ │ └── resources/ │ │ └── application.properties │ ├── Dockerfile │ └── pom.xml │ ├── docker-compose.yml # Docker Compose Configuration ├── .env.example # Environment Variables Template ├── .gitignore # Git Ignore Rules └── README.md # This File

We welcome contributions! Please follow these steps:

1. Fork the repository

2. Create a feature branch:

   git checkout -b feature/amazing-feature

3. Commit your changes:

   git commit -m 'Add amazing feature'

4. Push to the branch:

   git push origin feature/amazing-feature

5. Open a Pull Request

• Follow Java coding conventions
• Write unit tests for new features
• Update documentation
• Add Javadoc comments
• Keep code DRY (Don't Repeat Yourself)

Use conventional commits:

feat: add user profile picture upload
fix: resolve JWT token expiration issue
docs: update API endpoint documentation
refactor: improve product service caching logic
test: add integration tests for payment service

• Spring Boot Team for amazing framework
• Netflix OSS for Eureka
• Stripe for payment processing
• All open-source contributors

• Spring Boot Documentation
• Spring Cloud Gateway
• Netflix Eureka
• Apache Kafka
• Stripe API

• Microservices Architecture
• JWT Best Practices
• Docker Best Practices

Made with ❤️ by John Manohar

⭐ Star this repository if you find it helpful!