E-Commerce Microservices with Neo4j Graph Database

🎯 Project Overview

This is an enterprise-grade microservices architecture demonstrating:

• Spring Boot 3.x microservices
• Neo4j Graph Database for intelligent product recommendations
• Service Discovery with Netflix Eureka
• API Gateway with Spring Cloud Gateway
• Distributed Configuration with Spring Cloud Config
• Graph-based recommendations using Cypher queries
• Docker containerization for easy deployment

🏗️ Architecture

┌─────────────────┐
│   API Gateway   │ (Port 8080)
│  (Load Balance) │
└────────┬────────┘
         │
    ┌────┴────────────────────────┐
    │                             │
┌───▼──────────┐      ┌──────────▼─────┐
│  Product     │      │ Recommendation │
│  Catalog     │◄─────┤   Service      │
│  (Neo4j)     │      │   (Neo4j)      │
└──────────────┘      └────────────────┘
    │                           │
    │                           │
┌───▼──────────┐      ┌─────────▼──────┐
│   Order      │      │   Discovery    │
│  Service     │      │   Service      │
│  (MySQL)     │      │   (Eureka)     │
└──────────────┘      └────────────────┘
         │
    ┌────▼────────┐
    │   Config    │
    │   Server    │
    └─────────────┘

🚀 Technology Stack

• Java 17+
• Spring Boot 3.2.x
• Spring Cloud 2023.x
• Neo4j 5.x (Graph Database)
• MySQL 8.x (Order persistence)
• Netflix Eureka (Service Discovery)
• Spring Cloud Gateway (API Gateway)
• Docker & Docker Compose
• Lombok (Reduce boilerplate)
• Maven (Build tool)

📦 Services

Service	Port	Description
Discovery Service	8761	Eureka service registry
Config Server	8888	Centralized configuration
API Gateway	8080	Entry point, routing, load balancing
Product Catalog	8081	Product CRUD with Neo4j relationships
Recommendation Service	8082	Graph-based product recommendations
Order Service	8083	Order management and processing

🎯 Use Case: Intelligent Product Recommendations

This project demonstrates a real-world e-commerce scenario:

1. Product Relationships - Products connected by categories, brands, features in Neo4j
2. Collaborative Filtering - "Customers who bought X also bought Y"
3. Graph Traversal - Find similar products using graph algorithms
4. Real-time Updates - Order events update recommendation graphs

🛠️ Quick Start

Prerequisites

• Java 17+
• Docker & Docker Compose
• Maven 3.8+
• Git

One-Command Startup

docker-compose up -d

This will start:

• Neo4j database (http://localhost:7474)
• MySQL database
• All microservices
• Eureka Dashboard (http://localhost:8761)

Manual Build & Run

# Build all services
mvn clean install

# Start infrastructure
docker-compose up -d neo4j mysql

# Start services in order:
cd discovery-service && mvn spring-boot:run
cd config-server && mvn spring-boot:run
cd product-catalog-service && mvn spring-boot:run
cd recommendation-service && mvn spring-boot:run
cd order-service && mvn spring-boot:run
cd api-gateway && mvn spring-boot:run

📊 Neo4j Graph Model

Nodes

• Product: {id, name, description, price, stock}
• Category: {id, name}
• Brand: {id, name}
• Customer: {id, name, email}

Relationships

• (Product)-[:BELONGS_TO]->(Category)
• (Product)-[:MANUFACTURED_BY]->(Brand)
• (Product)-[:SIMILAR_TO {score}]->(Product)
• (Customer)-[:PURCHASED {date, quantity}]->(Product)
• (Product)-[:FREQUENTLY_BOUGHT_WITH {count}]->(Product)

🔥 Key Features Demonstrated

1. Graph-Based Recommendations

// Find similar products
MATCH (p:Product {id: $productId})-[:SIMILAR_TO]->(similar)
RETURN similar
ORDER BY similar.score DESC
LIMIT 5

2. Collaborative Filtering

// Customers who bought this also bought
MATCH (p:Product {id: $productId})<-[:PURCHASED]-(customer)
MATCH (customer)-[:PURCHASED]->(other)
WHERE other.id <> $productId
RETURN other, count(*) as frequency
ORDER BY frequency DESC

3. Category-Based Discovery

// Products in same category with high ratings
MATCH (p:Product {id: $productId})-[:BELONGS_TO]->(cat)
MATCH (similar)-[:BELONGS_TO]->(cat)
WHERE similar.id <> $productId
RETURN similar
ORDER BY similar.rating DESC

🧪 Testing the API

Using Postman

Import postman-collection.json for ready-to-use API requests.

Using cURL

# Create a product
curl -X POST http://localhost:8080/api/products \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MacBook Pro M3",
    "description": "Latest Apple laptop",
    "price": 2499.99,
    "stock": 50,
    "categoryId": "electronics",
    "brandId": "apple"
  }'

# Get recommendations
curl http://localhost:8080/api/recommendations/product/{productId}

# Place an order
curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust-001",
    "items": [
      {"productId": "prod-001", "quantity": 1}
    ]
  }'

# Find similar products
curl http://localhost:8080/api/products/{productId}/similar

🗂️ Project Structure

JavaMicroservices/
├── api-gateway/                    # Spring Cloud Gateway
│   ├── src/main/java/
│   ├── src/main/resources/
│   ├── Dockerfile
│   └── pom.xml
├── discovery-service/              # Eureka Server
├── config-server/                  # Spring Cloud Config
├── product-catalog-service/        # Product CRUD + Neo4j
├── recommendation-service/         # Graph queries for recommendations
├── order-service/                  # Order management
├── docker-compose.yml
├── README.md
└── postman-collection.json

🔍 Neo4j Browser Queries

Access Neo4j Browser at http://localhost:7474 (username: neo4j, password: password)

// View all products and categories
MATCH (p:Product)-[:BELONGS_TO]->(c:Category)
RETURN p, c

// Find recommendation paths
MATCH path = (p1:Product)-[*1..3]-(p2:Product)
WHERE p1.id = 'prod-001'
RETURN path
LIMIT 10

// Analyze purchase patterns
MATCH (c:Customer)-[purchased:PURCHASED]->(p:Product)
RETURN c.name, collect(p.name) as products

// Find products frequently bought together
MATCH (p1:Product)-[r:FREQUENTLY_BOUGHT_WITH]->(p2:Product)
WHERE r.count > 5
RETURN p1.name, p2.name, r.count
ORDER BY r.count DESC

🎓 Learning Outcomes

Spring Boot Patterns

• ✅ REST API design with Spring Web
• ✅ Service layer architecture
• ✅ DTO pattern with validation
• ✅ Global exception handling
• ✅ Spring Data integration

Microservices Patterns

• ✅ Service Discovery (Eureka)
• ✅ API Gateway routing
• ✅ Centralized configuration
• ✅ Inter-service communication
• ✅ Circuit breakers (Resilience4j)

Neo4j & Graph Databases

• ✅ Graph modeling for relationships
• ✅ Cypher query language
• ✅ Spring Data Neo4j
• ✅ Graph algorithms for recommendations
• ✅ Performance optimization with indexes

DevOps & Containerization

• ✅ Dockerfile creation
• ✅ Docker Compose orchestration
• ✅ Multi-container networking
• ✅ Environment configuration

🏢 Enterprise Relevance

This architecture is used in:

• Banking: Customer 360° view, fraud detection networks
• Retail: Product recommendations, inventory relationships
• Healthcare: Patient care networks, drug interaction graphs
• Social Networks: Friend recommendations, influence analysis

🔐 Security Considerations

For production deployment, add:

• Spring Security with OAuth2/JWT
• API rate limiting
• Database encryption
• Secret management (Vault)
• HTTPS/TLS
• Input validation & sanitization

📈 Monitoring & Observability

Ready for integration with:

• Spring Boot Actuator
• Prometheus + Grafana
• ELK Stack (Elasticsearch, Logstash, Kibana)
• Zipkin/Jaeger for distributed tracing

🚀 What to Learn Next

1. Event-Driven Architecture: Add Kafka/RabbitMQ for async communication
2. CQRS Pattern: Separate read/write models
3. Saga Pattern: Distributed transactions
4. Kubernetes: Deploy to K8s cluster
5. GraphQL: Alternative to REST
6. Neo4j Graph Data Science: Advanced ML algorithms
7. Reactive Programming: Spring WebFlux

🆚 Java vs C# Comparison

Concept	Java/Spring Boot	C#/.NET
Framework	Spring Boot	ASP.NET Core
DI Container	Spring IoC	Built-in DI
ORM	Spring Data JPA	Entity Framework Core
API	Spring Web	Web API Controllers
Config	application.yml	appsettings.json
Annotations	@RestController	[ApiController]
Async	CompletableFuture	Task<T>
Properties	Lombok @Data	C# properties/records

🤝 Contributing

This is an educational project. Feel free to:

• Add more services (payment, notification)
• Implement AI-based recommendations
• Add frontend (React/Angular)
• Enhance graph algorithms
• Add comprehensive tests

📝 License

MIT License - Feel free to use for learning and portfolio projects.

👨‍💻 Author

Created for demonstrating enterprise microservices architecture with Neo4j graph database integration.

---

Note: This project is optimized for learning and portfolio demonstration. For production use, implement proper security, monitoring, and error handling.