StyleHub Backend Microservices

StyleHub is a high-performance, multi-tenant Salon Booking & Management platform. This repository contains the backend microservices architecture built using Spring Boot 3.x, Spring Cloud, Keycloak IAM, RabbitMQ, Google Gemini AI, and MySQL, deployed on AWS EC2 via a CI/CD pipeline using GitHub Actions and Docker Hub.

---

🗺️ System Topology & Data Flow

graph TD
    Client[Frontend Client / React app] -->|HTTPS Requests| Gateway[Gateway Service: 8081]
    
    %% Registry & Auth %%
    Gateway -->|Registers with| Eureka[Eureka Server: 8070]
    Gateway -->|Verifies JWTs| Keycloak[Keycloak IAM: 8080]
    
    %% Gateway injects header %%
    Note[UserContextGatewayFilterFactory<br/>Injects X-User-Email header] -.- Gateway
    
    %% Downstream Services %%
    Gateway -->|Routes with X-User-Email| UserService[User Service: 5001]
    Gateway -->|Routes with X-User-Email| SalonService[Salon Service: 5002]
    Gateway -->|Routes with X-User-Email| CategoryService[Category Service: 5003]
    Gateway -->|Routes with X-User-Email| ServiceOffering[Service Offering Service: 5004]
    Gateway -->|Routes with X-User-Email| BookingService[Booking Service: 5005]
    Gateway -->|Routes with X-User-Email| PaymentService[Payment Service: 5006]
    Gateway -->|Routes with X-User-Email| ReviewService[Review Service: 5007]
    Gateway -->|Routes with X-User-Email| NotificationService[Notification Service: 5008]
    Gateway -->|Routes with X-User-Email| AIConsultant[AI Consultant Service: 5009]

    %% Database Layer %%
    UserService -->|Schema: user_db| MySQL[(MySQL Database: 3306)]
    SalonService -->|Schema: salon_db| MySQL
    CategoryService -->|Schema: category_db| MySQL
    ServiceOffering -->|Schema: service_offering_db| MySQL
    BookingService -->|Schema: booking_db| MySQL
    PaymentService -->|Schema: payment_db| MySQL
    ReviewService -->|Schema: review_db| MySQL
    NotificationService -->|Schema: notification_db| MySQL

    %% AI External API %%
    AIConsultant -->|Gemini Vision API| GeminiAPI[Google Gemini 2.5 Flash]

    %% Async Messaging (RabbitMQ) %%
    PaymentService ==>|Publish event| RabbitMQ{RabbitMQ Broker: 5672}
    RabbitMQ ==>|booking-queue| BookingService
    RabbitMQ ==>|notification-queue| NotificationService
    
    %% WebSocket %%
    NotificationService -->|STOMP over WebSockets| Client

Loading

---

🛠️ Microservices Catalog

Service Name	Port	Database	Context Consumption (X-User-Email)	Key Role
Eureka Server	8070	N/A	No	Service Discovery Registry
Gateway Service	8081	N/A	Enforcer / Injector	Policy Enforcement Point & Context Injection
User Service	5001	user_db	Yes	Local user profile store & Keycloak proxy
Salon Service	5002	salon_db	Yes	Storefront catalog & owner registrations
Category Service	5003	category_db	Yes	Service classifications
Service Offering	5004	service_offering_db	Yes	Specific treatments with duration & price; keyword search & full catalog APIs
Booking Service	5005	booking_db	Yes	Appointment slot booking & earnings reports
Payment Service	5006	payment_db	Yes	Razorpay Orders + Checkout.js with HMAC-SHA256 verification
Review Service	5007	review_db	Yes	Rating and feedback engine
Notification Service	5008	notification_db	Yes	RabbitMQ consumer & STOMP WebSocket broker
AI Consultant Service	5009	N/A (stateless)	Yes	Gemini 2.5 Flash Vision-powered style analysis & salon/service matching

---

🚀 CI/CD Pipeline & AWS Deployment

Why Pre-Built Docker Images?

The AWS EC2 Free Tier (t3.micro — 1 vCPU, 1 GB RAM) does not have sufficient resources to compile 11 Spring Boot microservices with Maven. Building locally would exhaust memory and cause Maven dependency download failures. To solve this, the project uses a pre-built Docker image strategy:

1. Build happens on GitHub Actions (powerful CI runners with 7 GB RAM).
2. Images are pushed to Docker Hub as ready-to-run containers.
3. EC2 only pulls and runs the pre-built images — no compilation required on the server.

CI Pipeline (GitHub Actions)

The CI pipeline (.github/workflows/ci.yml) triggers on every push to main and consists of two stages:

graph LR
    A[Push to main] --> B[Build & Test Stage]
    B --> C{All 11 services pass?}
    C -->|Yes| D[Build Docker Images]
    D --> E[Push to Docker Hub]
    E --> F[Images tagged with :latest and :commit-sha]
    C -->|No| G[Pipeline Fails]

Loading

Stage 1 — Build & Test (Matrix Strategy):

• Runs mvn test for all 11 microservices in parallel using a matrix strategy.
• Each service is tested against a MySQL 8.0 service container with Eureka discovery disabled.
• Uses JDK 21 (Temurin) with Maven dependency caching for faster builds.

Stage 2 — Build & Push Docker Images (runs only if all tests pass):

• Uses multi-stage Dockerfiles — the build stage compiles with maven:3.9.9-eclipse-temurin-21, and the runtime stage uses the lightweight eclipse-temurin:21-jre base image.
• Each image is pushed to Docker Hub with two tags: :latest and :<commit-sha> for version traceability.
• Uses GitHub Actions cache (type=gha) to speed up Docker layer rebuilds.

---

⚙️ Running Locally (Development)

Prerequisites

• Java 21 JDK, Maven 3.8+, Docker & Docker Compose

1. Build and Run via Docker Compose

# Build all services in parallel
docker compose build --parallel

# Start the cluster with wave-based scheduling
bash start-services.sh

2. E2E Integration Suite Validation

bash test-integration-suite.sh

(Verify that the console output returns E2E MICROSERVICES INTEGRATION COMPLETED 100% SUCCESSFULLY!)

---

💳 Payment Architecture: Razorpay Orders + Checkout.js

The payment service uses Razorpay Orders API + Checkout.js (not Payment Links) for processing Razorpay payments:

1. Backend creates a Razorpay Order via razorpay.orders.create() and returns the order_id, key_id, amount, payment_order_id, customer_name, and customer_email to the frontend.
2. Frontend opens the Razorpay Checkout.js modal in-page (no redirect needed).
3. On payment completion, Checkout.js returns razorpay_payment_id, razorpay_order_id, and razorpay_signature.
4. Frontend sends these to PATCH /api/payments/proceed/razorpay for server-side HMAC-SHA256 signature verification.
5. On success, the payment service publishes events to RabbitMQ (booking-queue + notification-queue) following the Choreography Saga Pattern.
6. On failure/cancel, the saga compensation flow transitions the booking from PENDING to CANCELLED, releasing the held slot.

---

🤖 AI Consultant Service Architecture

The AI Consultant Service (port 5009) provides Gemini 2.5 Flash Vision-powered style consultation:

1. Image Upload: Customer uploads a hairstyle/nail art image via POST /api/ai/consult (multipart/form-data, up to 10MB).
2. Context-Aware Prompting: The service fetches all available services from the Service Offering microservice via Feign, providing exact service names as context to Gemini.
3. Gemini Vision Analysis: Sends a multimodal request (image + structured prompt) to Gemini's generateContent endpoint with responseMimeType: application/json for structured JSON output.
4. Service Matching: For each AI-returned keyword, performs keyword search against the Service Offering database. Only exact name matches are retained to avoid hallucinated recommendations.
5. Salon Resolution: Extracts unique salon IDs from matched services and fetches salon details via Feign.
6. Response: Returns StyleConsultationResult with analysis text, detected keywords, matching services (with pricing/duration), and recommended salons.

---

🔐 Edge Security & Header Propagation (Performance Optimization)

In the original architecture, every downstream microservice independently resolved user identity by making synchronous Feign calls to the User Service, which then called Keycloak's /userinfo endpoint. This added ~110 ms of latency per request.

Optimized approach:

1. The API Gateway validates the JWT once and extracts the user's email from the token claims.
2. A custom UserContextGatewayFilterFactory injects X-User-Email as a trusted HTTP header.
3. Downstream services read @RequestHeader("X-User-Email") directly — no network calls needed.

This eliminated 16 redundant Feign calls and reduced average request latency by ~45%.