SmartCart: Microservices E-Commerce Platform

SmartCart is a scalable, cloud-native e-commerce backend system built with modern microservices architecture. This project demonstrates enterprise-grade patterns including event-driven communication, distributed tracing, circuit breakers, and comprehensive observability.

🎯 Project Goals

Microservices Architecture: Demonstrate loosely coupled, independently deployable services
Event-Driven Communication: Leverage Apache Kafka for asynchronous messaging
Observability: Implement distributed tracing, metrics, and logging
Resilience: Circuit breakers, retries, and fault tolerance patterns
Security: OAuth2/OIDC integration with Keycloak
DevOps Ready: Docker containerization and infrastructure as code

🏗️ Architecture Overview

Core Services

Service	Port	Database	Purpose
API Gateway	9000	-	Request routing, authentication, rate limiting
Product Service	8080	MongoDB	Product catalog management
Order Service	8081	MySQL	Order processing and management
Inventory Service	8082	MySQL	Stock management and availability
Notification Service	8083	-	Email notifications via Kafka events
Frontend	4200	-	Angular-based user interface

Infrastructure Components

Component	Port	Purpose
Keycloak	8181	Identity and Access Management
Kafka Broker	9092	Message streaming platform
Schema Registry	8085	Avro schema management
Kafka UI	8086	Kafka cluster management
Prometheus	9090	Metrics collection
Grafana	3000	Observability dashboards
Loki	3100	Log aggregation
Tempo	3110	Distributed tracing

🛠️ Technology Stack

Backend Technologies

Java 21 - Latest LTS version with modern language features
Spring Boot 3.2.4 - Microservices framework
Spring Cloud Gateway - API Gateway with routing and filters
Spring Security - OAuth2 Resource Server
Spring Data JPA - Database abstraction layer
Apache Kafka - Event streaming platform
Avro - Schema evolution for Kafka messages
Resilience4J - Circuit breaker pattern implementation
Flyway - Database migration tool

Frontend Technologies

Angular 18 - Modern web framework
TypeScript - Type-safe JavaScript
Tailwind CSS - Utility-first CSS framework
Angular OIDC Client - OAuth2/OIDC integration

Databases

MongoDB - Document database for product catalog
MySQL 8 - Relational database for orders and inventory

DevOps & Observability

Docker & Docker Compose - Containerization
Prometheus - Metrics collection and monitoring
Grafana - Visualization and alerting
Loki - Log aggregation system
Tempo - Distributed tracing backend
OpenTelemetry - Observability instrumentation

Security & Identity

Keycloak - Identity and Access Management
OAuth2/OIDC - Modern authentication standards
JWT Tokens - Stateless authentication

🏗️ System Architecture

High-Level Architecture Diagram

Key Architectural Patterns

1. API Gateway Pattern

Centralized entry point for all client requests
Cross-cutting concerns: authentication, rate limiting, routing
Circuit breaker integration for downstream service protection

2. Event-Driven Architecture

Asynchronous communication via Apache Kafka
Order placement triggers inventory checks and notifications
Schema Registry ensures message compatibility

3. Database per Service

Each microservice owns its data
MongoDB for document-based product catalog
MySQL for transactional order and inventory data

4. Circuit Breaker Pattern

Resilience4J implementation
Prevents cascade failures
Configurable fallback mechanisms

5. Distributed Tracing

OpenTelemetry integration
Request correlation across services
Performance bottleneck identification

🔐 Security Implementation

OAuth2/OIDC with Keycloak

Authentication Flow:
- Frontend redirects to Keycloak for login
- JWT tokens issued upon successful authentication
- Tokens validated by API Gateway
Authorization:
- Role-based access control (RBAC)
- Scope-based API access
- Token propagation to downstream services

Security Configuration

# Keycloak Realm Configuration
Realm: spring-microservices-security-realm
Client ID: microservices-client
Valid Redirect URIs: http://localhost:4200/*

📈 Monitoring & Observability

Grafana Dashboards

Key Metrics Tracked

Application Metrics: Request rate, response time, error rate
Business Metrics: Orders placed, products viewed, inventory levels
Infrastructure Metrics: CPU, memory, database connections
Kafka Metrics: Message throughput, consumer lag, topic partitions

Log Aggregation with Loki

Distributed Tracing

End-to-end request tracing across all services
Performance optimization insights
Error root cause analysis

🎮 User Interface

Product Management

Order Processing

📧 Event-Driven Notifications

Kafka Integration

Message Flow

Order Placed → Kafka Topic order-placed
Notification Service → Consumes order events
Email Notification → Sent to customer

Kafka Topics & Schema Management

🐳 Containerization

Docker Services Overview

Multi-Stage Docker Builds

Each service includes optimized Dockerfile with:

Multi-stage builds for smaller images
Non-root user execution
Health check endpoints
Graceful shutdown handling

🧪 Testing Strategy

Test Pyramid Implementation

Unit Tests: JUnit 5, Mockito
Integration Tests: TestContainers for database testing
Contract Tests: API contract validation
End-to-End Tests: REST Assured for API testing

Test Containers Usage

@Testcontainers
class OrderServiceIntegrationTest {
    @Container
    static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.3.0");
    
    @Container
    static KafkaContainer kafka = new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:7.5.0"));
}

🔄 CI/CD Pipeline (Recommended)

GitHub Actions Workflow

name: Microservices CI/CD
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up JDK 21
        uses: actions/setup-java@v3
        with:
          java-version: '21'
      - name: Run Tests
        run: ./mvnw test
      - name: Build Docker Images
        run: docker-compose build

🚀 Production Deployment

Kubernetes Deployment (Future Enhancement)

Helm charts for service deployment
Horizontal Pod Autoscaling (HPA)
Service mesh integration (Istio)
External secrets management

Environment-Specific Configurations

Development: Local Docker Compose
Staging: Kubernetes cluster with external databases
Production: Cloud-native services (AWS RDS, MSK, etc.)

📚 API Documentation

Swagger/OpenAPI Integration

Access comprehensive API documentation:

Aggregated Docs: http://localhost:9000/swagger-ui.html
Product Service: http://localhost:8080/swagger-ui.html
Order Service: http://localhost:8081/swagger-ui.html
Inventory Service: http://localhost:8082/swagger-ui.html

Sample API Endpoints

Products

GET /api/products          # Get all products
POST /api/products         # Create new product
GET /api/products/{id}     # Get product by ID

Orders

POST /api/orders           # Place new order
GET /api/orders/{id}       # Get order details

Inventory

GET /api/inventory/{skuCode}/status  # Check inventory status

🔧 Development Tools

Recommended IDE Setup

IntelliJ IDEA with Spring Boot plugin
VS Code with Java Extension Pack
Docker Desktop for container management

Code Quality Tools

SonarQube integration for code analysis
Checkstyle for coding standards
SpotBugs for bug detection

🤝 Contributing

Development Guidelines

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open Pull Request

Code Standards

Follow Java coding conventions
Write comprehensive tests
Update documentation
Use conventional commit messages

🐛 Troubleshooting

Common Issues

1. Port Conflicts

# Check port usage
netstat -ano | findstr :8080
# Kill process if needed
taskkill /PID <process_id> /F

2. Database Connection Issues

# Verify MySQL containers are running
docker ps | grep mysql
# Check logs
docker logs inventory-service-mysql

3. Kafka Connection Problems

# Verify Kafka cluster health
docker exec -it broker kafka-topics --bootstrap-server localhost:9092 --list

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Spring Boot Team for the excellent framework
Apache Kafka community for event streaming platform
Grafana Labs for observability tools
Keycloak team for identity management
TestContainers for integration testing

📞 Contact & Support

GitHub Issues: Report bugs or request features
Author: Chanuth Silva
Email: [Your Email]

⭐ Star this repository if you find it helpful for learning microservices architecture!

🚀 Quick Start

Prerequisites

Ensure you have the following installed on your system:

Java 21 or later
Node.js 18+ and npm
Docker and Docker Compose
Git

1. Clone the Repository

git clone https://github.com/Chanuth-silva10/microservices-springboot-kafka-grafana.git
cd microservices-springboot-kafka-grafana

2. Start Infrastructure Services

Each service has its own Docker Compose file for modular deployment:

# Start API Gateway with observability stack
cd api-gateway
docker-compose up -d
cd ..

# Start Order Service with Kafka ecosystem
cd order-service
docker-compose up -d
cd ..

# Start Inventory Service with MySQL
cd inventory-service
docker-compose up -d
cd ..

# Start Product Service with MongoDB
cd product-service
docker-compose up -d
cd ..

3. Build and Run Backend Services

# Build all services
./mvnw clean package -DskipTests

# Run each service (in separate terminals)
cd api-gateway && ./mvnw spring-boot:run
cd product-service && ./mvnw spring-boot:run  
cd order-service && ./mvnw spring-boot:run
cd inventory-service && ./mvnw spring-boot:run
cd notification-service && ./mvnw spring-boot:run

4. Start Frontend Application

cd frontend
npm install
npm start

The application will be available at:

Frontend: http://localhost:4200
API Gateway: http://localhost:9000
Swagger UI: http://localhost:9000/swagger-ui.html

🔧 Configuration

Environment Variables

Key configuration properties can be found in each service's application.properties:

API Gateway (`api-gateway/src/main/resources/application.properties`)

server.port=9000
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8181/realms/spring-microservices-security-realm
product.service.url=http://localhost:8080
order.service.url=http://localhost:8081
inventory.service.url=http://localhost:8082

Kafka Configuration (`order-service` & `notification-service`)

spring.kafka.bootstrap-servers=localhost:9092
spring.kafka.producer.properties.schema.registry.url=http://127.0.0.1:8085

Database Configuration

MongoDB (Product Service): mongodb://localhost:27017/product-service
MySQL (Order Service): jdbc:mysql://localhost:3307/order_service
MySQL (Inventory Service): jdbc:mysql://localhost:3316/inventory_service

📊 Monitoring & Observability

Access the observability stack:

Grafana Dashboards: http://localhost:3000
Prometheus Metrics: http://localhost:9090
Kafka UI: http://localhost:8086
Keycloak Admin: http://localhost:8181 (admin/admin)

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.idea		.idea
api-gateway		api-gateway
frontend		frontend
inventory-service		inventory-service
notification-service		notification-service
order-service		order-service
product-service		product-service
.gitignore		.gitignore
README.md		README.md

Chanuth-silva10/microservices-springboot-kafka-grafana

Folders and files

Latest commit

History

Repository files navigation