Logistics Service Module

Java | Maven | MongoDB | Kafka | Spring Boot

📦 Overview

A resilient logistics orchestration service that manages:

• Home Deliveries (HDS)
• Drop Zone Network (DZN) deliveries
• Real-time fraud detection
• Automated error recovery

Built for seamless integration with Order/Payment services in a microservices architecture.

---

⚙️ Tech Stack

Component	Technology
Language	Java 17
Framework	Spring Boot 3.2
Build Tool	Maven
Database	MongoDB 6.0+
Event Streaming	Kafka 3.4
Cache	Redis 7
API Docs	OpenAPI 3.0

---

🚀 Quick Start

1. Prerequisites

# Core dependencies
java -version  # 17+
mvn -v         # 3.9+
docker --version

# Required containers
docker-compose up -d mongodb kafka redis

2. Configuration

Create .env:

# MongoDB
SPRING_DATA_MONGODB_URI=mongodb://localhost:27017/logistics

# Kafka
KAFKA_BOOTSTRAP_SERVERS=localhost:9092

# Fraud Detection
FRAUD_THRESHOLD=0.85

3. Build & Run

mvn clean install
mvn spring-boot:run -Dspring-boot.run.profiles=dev

API Docs: http://localhost:8080/swagger-ui.html

---

🧪 Testing Matrix

Unit Tests

mvn test

Tests:

• DeliveryOrchestratorServiceTest
• FraudDetectionAlgorithmTest
• MongoRepositoryIntegrationTest

Integration Tests

mvn verify -Pintegration-test

Validates:
✅ MongoDB connectivity
✅ Kafka event publishing
✅ Redis cache synchronization

Manual API Tests

# Create delivery
curl -X POST http://localhost:8080/api/v1/deliveries \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ord_123",
    "destinationType": "DROP_ZONE",
    "recipient": {
      "phone": "+15551234567",
      "qrRequirement": true
    }
  }'

# Force error case
curl -X POST http://localhost:8080/api/v1/deliveries \
  -H "X-TEST-MODE: FAIL_HDS" \
  -d '{"orderId": "ord_fail1", "destinationType": "HOME"}'

---

🔗 Service Integration

Expected Upstream Events

@KafkaListener(topics = "order-events")
public void handleOrderCreated(OrderEvent event) {
  // Sample payload:
  // {"eventType":"ORDER_CREATED","orderId":"ord_123","userId":"usr_456"}
}

Downstream API Contracts

1. Payment Service Verification

GET /api/payments/validate?orderId={orderId}
Headers:
  X-Service-Auth: ${payment.service.key}

2. Inventory Service Reservation

POST /api/inventory/lock
{
  "items": ["sku_123"],
  "orderId": "ord_123",
  "ttlMinutes": 30
}

---

📊 Monitoring

Metric	Grafana Dashboard	Alert Threshold
Delivery Success Rate	delivery_sli	< 99.5%
Fraud Positive Rate	fraud_analysis	> 15%
MongoDB Op Latency	mongodb_performance	> 200ms

Log Query Example:

// Kibana (ES) query for error analysis
service.name:"logistics-service" AND level:ERROR 
| stats count() by exception.class

---

🛠 Troubleshooting

Common Issues:

1. MongoDB Connection Timeout

   • Verify replica set status:

     docker exec -it mongodb mongosh --eval "rs.status()"
     

   • Check network latency between services

2. Kafka Message Backlog

   # Check consumer lag
   kafka-consumer-groups --bootstrap-server localhost:9092 \
     --group logistics-group --describe
   

3. Fraud False Positives

   • Adjust thresholds in FraudDetectionProperties
   • Whitelist test users in MongoDB:

     db.fraud_whitelist.insertOne({userId: "test_usr"})
     

---

🔜 Roadmap

• Multi-region MongoDB deployment
• ML-based fraud detection upgrade
• GraphQL API gateway integration

---

📮 Contact:
[email protected]
GitHub Issues

License: Apache 2.0

---

Pro Tip: Use the included docker-compose.test.yml for isolated integration testing:

docker-compose -f docker-compose.test.yml up --abort-on-container-exit