IntelliCart - AI-Powered E-Commerce Backend System

Architecture Overview

IntelliCart is a production-grade, microservices-based e-commerce platform built with:

• Backend Services: Java 17 + Spring Boot 3.x
• AI Services: Python FastAPI with ML capabilities
• Message Broker: Apache Kafka for event-driven architecture
• Databases: PostgreSQL (primary), Redis (cache), Elasticsearch (search)
• Infrastructure: Spring Cloud (Eureka, Config Server, API Gateway)

System Architecture

                                    ┌─────────────────┐
                                    │   API Gateway   │
                                    │   (Port 8080)   │
                                    └────────┬────────┘
                                             │
                    ┌────────────────────────┼────────────────────────┐
                    │                        │                        │
         ┌──────────▼─────────┐   ┌─────────▼────────┐   ┌──────────▼─────────┐
         │   User Service     │   │ Product Service  │   │  Order Service     │
         │   (Port 8081)      │   │  (Port 8082)     │   │  (Port 8083)       │
         └────────────────────┘   └──────────────────┘   └────────────────────┘
                    │                        │                        │
                    └────────────────────────┼────────────────────────┘
                                             │
                                    ┌────────▼────────┐
                                    │  Kafka Broker   │
                                    │  (Port 9092)    │
                                    └────────┬────────┘
                                             │
         ┌───────────────────────────────────┼───────────────────────────────────┐
         │                                   │                                   │
┌────────▼─────────┐            ┌───────────▼──────────┐          ┌────────────▼────────┐
│ Inventory Service│            │ Notification Service │          │  Payment Service    │
│  (Port 8084)     │            │    (Port 8086)       │          │   (Port 8085)       │
└──────────────────┘            └──────────────────────┘          └─────────────────────┘

         ┌─────────────────────────────────────────────────────────┐
         │                    AI Services (Python)                  │
         ├──────────────────────┬──────────────────┬───────────────┤
         │ Recommendation       │ Fraud Detection  │ Search Service│
         │ (Port 8090)          │ (Port 8091)      │ (Port 8092)   │
         └──────────────────────┴──────────────────┴───────────────┘

         ┌──────────────────────────────────────────────────────────┐
         │              Infrastructure Services                      │
         ├────────────────────┬─────────────────────────────────────┤
         │ Service Registry   │      Config Server                  │
         │ (Eureka: 8761)     │      (Port 8888)                    │
         └────────────────────┴─────────────────────────────────────┘

Services Overview

Core Backend Services (Java Spring Boot)

1. User Service - User management, authentication, profiles
2. Product Service - Product catalog, categories, pricing
3. Order Service - Order processing, order history
4. Inventory Service - Stock management, warehouse operations
5. Payment Service - Payment processing, transaction management
6. Notification Service - Email/SMS notifications

AI Services (Python FastAPI)

7. Recommendation Service - ML-based product recommendations
8. Fraud Detection Service - Real-time fraud detection using ML
9. Search Service - Elasticsearch-powered product search

Infrastructure Services

10. API Gateway - Single entry point, routing, load balancing
11. Service Registry - Eureka service discovery
12. Config Server - Centralized configuration management

Technology Stack

• Java: 17+
• Spring Boot: 3.2.x
• Spring Cloud: 2023.0.x
• Python: 3.11+
• FastAPI: 0.109+
• PostgreSQL: 15+
• Redis: 7+
• Kafka: 3.6+
• Elasticsearch: 8.x
• Docker: 24+

Prerequisites

• JDK 17 or higher
• Maven 3.8+
• Python 3.11+
• Docker & Docker Compose
• PostgreSQL 15+
• Redis 7+
• Apache Kafka 3.6+

🚀 Current Implementation Status

✅ ALL PHASES COMPLETED (100%)

• ✅ Phase 1: Core Services (User, Product) - 100%
• ✅ Phase 2: Order Management (Order, Inventory) - 100%
• ✅ Phase 3: Event-Driven Architecture (Kafka) - 100%
• ✅ Phase 4: API Gateway (JWT, Rate Limiting, Routing) - 100%
• ✅ Phase 5: AI Services (Recommendation, Fraud Detection, Search) - 100%
• ✅ Phase 6: Advanced Features (Complete infrastructure) - 100%
• ✅ Phase 7: Testing (Unit tests, CI/CD) - 100%
• ✅ Phase 8: DevOps (Kubernetes, Helm, GitHub Actions) - 100%

What's Included:

✅ 11 fully functional microservices (8 Java + 3 Python) ✅ Complete event-driven architecture ✅ AI-powered recommendations and fraud detection ✅ Advanced search with Elasticsearch ✅ API Gateway with JWT authentication ✅ Comprehensive unit tests ✅ CI/CD pipeline with GitHub Actions ✅ Kubernetes deployment manifests ✅ Helm charts for easy deployment ✅ Complete documentation (12 files)

See COMPLETION_SUMMARY.md for full details

Quick Start

1. Clone and Build

# Build all Java services
mvn clean install -DskipTests

2. Start Infrastructure with Docker

docker-compose up -d postgres redis kafka elasticsearch

3. Start Services (in order)

# 1. Config Server
cd config-server && mvn spring-boot:run

# 2. Service Registry
cd service-registry && mvn spring-boot:run

# 3. Core Services
cd user-service && mvn spring-boot:run
cd product-service && mvn spring-boot:run
cd order-service && mvn spring-boot:run
cd inventory-service && mvn spring-boot:run
cd payment-service && mvn spring-boot:run
cd notification-service && mvn spring-boot:run

# 4. API Gateway
cd api-gateway && mvn spring-boot:run

# 5. AI Services
cd recommendation-service && uvicorn main:app --port 8090
cd fraud-detection-service && uvicorn main:app --port 8091
cd search-service && uvicorn main:app --port 8092

4. Or Use Docker Compose (Recommended)

docker-compose up --build

API Documentation

Once services are running, access Swagger UI:

• API Gateway: http://localhost:8080/swagger-ui.html
• User Service: http://localhost:8081/swagger-ui.html
• Product Service: http://localhost:8082/swagger-ui.html
• Order Service: http://localhost:8083/swagger-ui.html

Service Ports

Service	Port
API Gateway	8080
User Service	8081
Product Service	8082
Order Service	8083
Inventory Service	8084
Payment Service	8085
Notification Service	8086
Recommendation Service	8090
Fraud Detection Service	8091
Search Service	8092
Config Server	8888
Eureka Server	8761

Kafka Topics

• order.created - New order events
• order.confirmed - Order confirmation events
• order.cancelled - Order cancellation events
• payment.processed - Payment completion events
• inventory.updated - Stock update events
• user.activity - User behavior tracking
• fraud.detected - Fraud alerts

Database Schemas

User Service DB: userdb

• users
• roles
• user_roles

Product Service DB: productdb

• products
• categories
• product_categories

Order Service DB: orderdb

• orders
• order_items

Inventory Service DB: inventorydb

• inventory
• warehouse

Payment Service DB: paymentdb

• payments
• transactions

Authentication

All APIs require JWT authentication (except registration/login).

Get JWT Token:

POST /api/auth/login
{
  "email": "user@example.com",
  "password": "password123"
}

Use Token:

Authorization: Bearer <your-jwt-token>

Testing APIs

Import the Postman collection from postman/IntelliCart.postman_collection.json

Sample API Calls:

# Register User
curl -X POST http://localhost:8080/api/users/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"pass123","firstName":"John","lastName":"Doe"}'

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

# Get Products
curl -X GET http://localhost:8080/api/products \
  -H "Authorization: Bearer <token>"

# Create Order
curl -X POST http://localhost:8080/api/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"productId":1,"quantity":2}]}'

Event-Driven Order Flow

1. Order Created → Order Service publishes order.created
2. Inventory Check → Inventory Service consumes event, reserves stock
3. Fraud Check → Fraud Detection Service evaluates risk
4. Payment Processing → Payment Service processes payment
5. Notification → Notification Service sends confirmation
6. Recommendation Update → Recommendation Service updates user profile

Monitoring & Health

• Eureka Dashboard: http://localhost:8761
• Actuator endpoints: /actuator/health, /actuator/metrics
• Kafka UI: http://localhost:9000 (if configured)

Development Guidelines

Code Structure

service-name/
├── src/main/java/com/intellicart/servicename/
│   ├── controller/
│   ├── service/
│   ├── repository/
│   ├── model/
│   ├── dto/
│   ├── config/
│   ├── exception/
│   └── ServiceNameApplication.java
├── src/main/resources/
│   ├── application.yml
│   └── bootstrap.yml
└── pom.xml

Best Practices

• Use DTOs for API requests/responses
• Never expose entities directly
• Implement global exception handling
• Use proper HTTP status codes
• Add validation annotations
• Implement circuit breakers for external calls
• Use Redis for frequently accessed data
• Log all important operations

Configuration Management

All service configurations are centralized in Config Server. Configuration files are in config-server/src/main/resources/config/

Troubleshooting

Services not registering with Eureka

• Ensure Config Server is running first
• Check bootstrap.yml has correct config server URL
• Wait 30 seconds for registration

Kafka connection issues

• Verify Kafka is running: docker ps | grep kafka
• Check broker address in application.yml

Database connection errors

• Ensure PostgreSQL is running
• Verify credentials in config files
• Check database exists

Production Considerations

• Use environment-specific configs (dev, staging, prod)
• Implement distributed tracing (Zipkin/Jaeger)
• Add rate limiting at API Gateway
• Use database connection pooling
• Implement proper backup strategies
• Set up monitoring (Prometheus + Grafana)
• Use Kubernetes for orchestration
• Implement blue-green deployment

License

MIT License

📚 Complete Documentation

• 🚀 GETTING_STARTED.md - Quick start guide (5 minutes)
• 📖 SETUP.md - Detailed setup instructions
• 🧪 TESTING_GUIDE.md - Comprehensive testing scenarios
• 🗄️ DATABASE_SCHEMA.md - Complete database design
• 🏗️ ARCHITECTURE.md - System architecture deep dive
• 🚀 DEPLOYMENT.md - Deployment strategies (Docker, K8s, Cloud)
• 📊 PROJECT_STATUS.md - Implementation status and roadmap
• 📝 BUILD_SUMMARY.md - What has been built

🎯 Key Features Implemented

Core Functionality

✅ User registration and JWT authentication ✅ Product catalog with categories ✅ Advanced product search and filtering ✅ Redis caching for performance ✅ Order creation and management ✅ Automatic inventory management via events ✅ Event-driven architecture with Kafka ✅ Service discovery with Eureka ✅ Centralized configuration ✅ Circuit breake