System Architecture

  ┌─────────────────────────────────────────────────────────────────────┐
  │                       CLIENT TIER                                    │
  │   🌐 Browser / Mobile App / Postman (HTTP Requests)                 │
  └────────────────────────────┬────────────────────────────────────────┘
                               │  REST / HTTP
                               ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │                     API GATEWAY (Port 8080)                          │
  │         Routes requests to the right microservice                   │
  └──────┬───────────────────────┬──────────────────────┬───────────────┘
         │                       │                      │
         ▼                       ▼                      ▼
  ┌─────────────┐     ┌─────────────────┐     ┌─────────────────┐
  │  Product    │     │  Order Service  │     │  User Service   │
  │  Service   │     │  (Port 8082)    │     │  (Port 8083)    │
  │  (Port 8081)│     │                │     │                 │
  └──────┬──────┘     └────────┬────────┘     └────────┬────────┘
         │                     │                       │
         ▼            ┌────────┘         ┌─────────────┘
  ┌─────────────┐     ▼                  ▼
  │ Redis Cache │   Azure          ┌─────────────────────────────┐
  │ (fast data) │   Service Bus ──▶│  Notification Service       │
  └─────────────┘   (messages)    │  (Port 8084)                │
         │                        └─────────────────────────────┘
         ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │                      DATA TIER                                       │
  │   MySQL Database      |     Azure Key Vault (secrets/passwords)     │
  └─────────────────────────────────────────────────────────────────────┘

Components at a Glance

Request–Response Cycle

  STEP 1: Client sends HTTP Request
  ──────────────────────────────────────────────────────────
  GET /api/products/101 HTTP/1.1
  Host: shopease.com
  Accept: application/json
  Authorization: Bearer eyJhbGciOiJIUzI1Ni...
  ──────────────────────────────────────────────────────────

  STEP 2: Server processes it and sends HTTP Response
  ──────────────────────────────────────────────────────────
  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "id": 101,
    "name": "Wireless Headphones",
    "price": 2499.00,
    "stock": 50
  }
  ──────────────────────────────────────────────────────────

HTTP Methods (CRUD)

Spring Boot: Your First REST Endpoint

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @Autowired
    private ProductService productService;

    // GET /api/products          → list all products
    @GetMapping
    public List<Product> getAllProducts() {
        return productService.getAllProducts();
    }

    // GET /api/products/101      → get one product
    @GetMapping("/{id}")
    public ResponseEntity<Product> getProduct(@PathVariable Long id) {
        Product product = productService.getProductById(id);
        return ResponseEntity.ok(product);  // 200 OK
    }

    // POST /api/products         → create a product
    @PostMapping
    public ResponseEntity<Product> createProduct(@RequestBody Product product) {
        Product saved = productService.save(product);
        return ResponseEntity.status(HttpStatus.CREATED).body(saved);  // 201 Created
    }

    // DELETE /api/products/101   → delete a product
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteProduct(@PathVariable Long id) {
        productService.delete(id);
        return ResponseEntity.noContent().build();  // 204 No Content
    }
}

JSON — The Language of APIs

// Java Object ──Spring Boot converts──▶ JSON Response
public class Product {
    private Long id;          // "id": 101
    private String name;      // "name": "Headphones"
    private double price;     // "price": 2499.00
    // getters + setters
}

// Client receives:
// { "id": 101, "name": "Headphones", "price": 2499.00 }

Monolith vs Microservices

  ┌──────────────────────────────┐
  │   ONE BIG APPLICATION        │
  │                              │
  │  Users + Products + Orders   │
  │  + Payments + Notifications  │
  │  + Admin + Reports + ...     │
  │                              │
  │  Deploy as ONE .jar file     │
  └──────────────────────────────┘

  Problem: If Product code has a bug,
  the ENTIRE app goes down.
  Scaling: you must scale everything.

  ┌──────────┐  ┌──────────┐
  │ Product  │  │  Order   │
  │ Service  │  │ Service  │
  └──────────┘  └──────────┘
  ┌──────────┐  ┌──────────┐
  │  User    │  │ Notif.   │
  │ Service  │  │ Service  │
  └──────────┘  └──────────┘

  Each is a separate .jar file.
  Product bug? Only Product restarts.
  Need to scale Orders? Scale only Orders.

Key Principles of Microservices

• 1
  Single Responsibility: Each service does ONE thing. Product Service only manages products. It doesn't care about orders or users.
• 2
  Own Database: Each service has its own MySQL database/schema. Order Service can't directly query Product Service's database.
• 3
  Communicate via API or Messages: Services talk to each other via REST calls or message queues (Service Bus).
• 4
  Independent Deployment: Deploy Product Service without touching Order Service.
• 5
  Independently Scalable: If Orders spike during a sale, scale only the Order Service.

ShopEase: Inter-Service Communication

// ── Order Service needs product details ──
// It calls Product Service's REST API using RestTemplate or WebClient

@Service
public class OrderService {

    @Autowired
    private RestTemplate restTemplate;   // HTTP client

    @Autowired
    private OrderRepository orderRepository;

    public Order placeOrder(Long productId, int quantity, String userId) {
        // Step 1: Call Product Service to check stock + get price
        String productUrl = "http://product-service/api/products/" + productId;
        Product product = restTemplate.getForObject(productUrl, Product.class);

        if (product == null || product.getStock() < quantity) {
            throw new InsufficientStockException("Not enough stock");
        }

        // Step 2: Save order to Order Service's own database
        Order order = new Order();
        order.setProductId(productId);
        order.setQuantity(quantity);
        order.setTotalAmount(product.getPrice() * quantity);
        order.setUserId(userId);
        order.setStatus("PLACED");

        Order savedOrder = orderRepository.save(order);

        // Step 3: Publish event to Azure Service Bus → Notification Service picks it up
        orderEventPublisher.publishOrderPlaced(savedOrder);

        return savedOrder;
    }
}

// ── RestTemplate Bean Configuration ──
@Configuration
public class AppConfig {
    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

Project Structure (Standard Layered Architecture)

  product-service/
  ├── src/main/java/com/shopease/product/
  │   ├── ProductServiceApplication.java    ← Entry point
  │   ├── controller/
  │   │   └── ProductController.java        ← Layer 1: Handle HTTP requests
  │   ├── service/
  │   │   ├── ProductService.java           ← Layer 2: Business logic (interface)
  │   │   └── ProductServiceImpl.java       ←          Implementation
  │   ├── repository/
  │   │   └── ProductRepository.java        ← Layer 3: Database operations
  │   ├── entity/
  │   │   └── Product.java                  ← Database table mapping
  │   ├── dto/
  │   │   ├── ProductRequest.java           ← What client sends
  │   │   └── ProductResponse.java          ← What server returns
  │   ├── exception/
  │   │   ├── ProductNotFoundException.java
  │   │   └── GlobalExceptionHandler.java
  │   └── config/
  │       └── AppConfig.java                ← Beans, Redis, etc.
  └── src/main/resources/
      └── application.properties            ← All configuration

Request Flow Through Layers

  Client (Postman)
       │  GET /api/products/101
       ▼
  ┌──────────────────────┐
  │  ProductController   │  ← receives HTTP request
  │  @RestController     │    validates URL, path variables
  └──────────┬───────────┘    calls service layer
             │
             ▼
  ┌──────────────────────┐
  │  ProductService      │  ← business logic lives here
  │  @Service            │    check stock, apply discount
  └──────────┬───────────┘    calls repository layer
             │
             ▼
  ┌──────────────────────┐
  │  ProductRepository   │  ← talks to database
  │  extends JpaRepo...  │    SQL is auto-generated!
  └──────────┬───────────┘
             │
             ▼
         MySQL DB

Entry Point

@SpringBootApplication   // = @Configuration + @ComponentScan + @EnableAutoConfiguration
public class ProductServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProductServiceApplication.class, args);
        // Starts embedded Tomcat server on port 8081
    }
}

Dependency Injection (DI) — Spring's Magic

// ── Without DI (old way) — tightly coupled, hard to test ──
public class ProductController {
    private ProductService service = new ProductServiceImpl();  // You create it
    private ProductRepository repo = new ProductRepository();   // You create it
}

// ── With DI (Spring way) — loosely coupled ──
@RestController
public class ProductController {
    @Autowired                          // Spring injects it for you
    private ProductService productService;

    // OR use constructor injection (recommended):
}

@RestController
@RequiredArgsConstructor  // Lombok generates constructor
public class ProductController {
    private final ProductService productService; // Spring injects via constructor
}

// ── Spring manages beans with these annotations ──
@Component    // Generic bean
@Service      // Business logic layer
@Repository   // Data access layer
@Controller   // Web layer
@RestController // @Controller + @ResponseBody

application.properties

// src/main/resources/application.properties

# Server
server.port=8081
spring.application.name=product-service

# MySQL Database
spring.datasource.url=jdbc:mysql://localhost:3306/shopease_products
spring.datasource.username=${DB_USERNAME}    # from environment / Key Vault
spring.datasource.password=${DB_PASSWORD}    # NEVER hardcode passwords!
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# JPA/Hibernate
spring.jpa.hibernate.ddl-auto=update        # auto-create/update tables
spring.jpa.show-sql=true                    # logs all SQL (disable in prod)
spring.jpa.properties.hibernate.format_sql=true

# Redis
spring.cache.type=redis
spring.redis.host=localhost
spring.redis.port=6379

# Logging
logging.level.com.shopease=DEBUG

Entity — Java Class ↔ Database Table

// This Java class maps to a MySQL table called "products"
@Entity
@Table(name = "products")
@Data                    // Lombok: generates getters, setters, toString, equals
@NoArgsConstructor
@AllArgsConstructor
public class Product {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY) // AUTO_INCREMENT
    private Long id;

    @Column(nullable = false, length = 100)
    private String name;

    @Column(nullable = false)
    private double price;

    @Column(nullable = false)
    private int stock;

    @Column(length = 50)
    private String category;

    @Column(name = "created_at")
    private LocalDateTime createdAt = LocalDateTime.now();
}

// Spring generates this SQL automatically:
// CREATE TABLE products (
//   id BIGINT AUTO_INCREMENT PRIMARY KEY,
//   name VARCHAR(100) NOT NULL,
//   price DOUBLE NOT NULL,
//   stock INT NOT NULL,
//   category VARCHAR(50),
//   created_at DATETIME
// );

Repository — Zero SQL for CRUD

// Extend JpaRepository → GET FREE CRUD methods!
@Repository
public interface ProductRepository extends JpaRepository<Product, Long> {
    //                                                     ↑Entity  ↑ID type

    // ─── FREE methods from JpaRepository ───
    // save(product)              → INSERT or UPDATE
    // findById(id)               → SELECT WHERE id = ?
    // findAll()                  → SELECT * FROM products
    // deleteById(id)             → DELETE WHERE id = ?
    // count()                    → SELECT COUNT(*)
    // existsById(id)             → SELECT 1 WHERE id = ?

    // ─── Custom queries — just name the method! ───
    List<Product> findByCategory(String category);
    // SELECT * FROM products WHERE category = ?

    List<Product> findByPriceLessThan(double price);
    // SELECT * FROM products WHERE price < ?

    List<Product> findByCategoryAndPriceLessThanOrderByPriceAsc(
        String category, double maxPrice);
    // SELECT * FROM products WHERE category = ? AND price < ? ORDER BY price ASC

    Optional<Product> findByName(String name);

    // ─── Custom JPQL query (Java, not SQL) ───
    @Query("SELECT p FROM Product p WHERE p.stock > 0 ORDER BY p.price ASC")
    List<Product> findAvailableProductsByPrice();

    // ─── Native SQL query ───
    @Query(value = "SELECT * FROM products WHERE price BETWEEN ?1 AND ?2",
           nativeQuery = true)
    List<Product> findByPriceRange(double min, double max);
}

Service Layer using Repository

@Service
@Transactional  // all DB ops in this class are transactional
public class ProductServiceImpl implements ProductService {

    @Autowired
    private ProductRepository productRepository;

    @Override
    public List<Product> getAllProducts() {
        return productRepository.findAll();
    }

    @Override
    public Product getProductById(Long id) {
        return productRepository.findById(id)
            .orElseThrow(() -> new ProductNotFoundException(id));
    }

    @Override
    public Product createProduct(Product product) {
        return productRepository.save(product);  // INSERT
    }

    @Override
    public Product updateProduct(Long id, Product updated) {
        Product existing = getProductById(id);
        existing.setName(updated.getName());
        existing.setPrice(updated.getPrice());
        existing.setStock(updated.getStock());
        return productRepository.save(existing);  // UPDATE (id already set)
    }

    @Override
    public void deleteProduct(Long id) {
        if (!productRepository.existsById(id)) {
            throw new ProductNotFoundException(id);
        }
        productRepository.deleteById(id);
    }
}

Table Relationships

// One Order has MANY OrderItems  (OneToMany)
@Entity
@Table(name = "orders")
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String userId;
    private String status;  // PLACED, SHIPPED, DELIVERED
    private double totalAmount;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    private List<OrderItem> items;  // one order → many items
}

// One OrderItem belongs to ONE Order (ManyToOne)
@Entity
@Table(name = "order_items")
public class OrderItem {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private Long productId;
    private int quantity;
    private double price;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "order_id")  // foreign key column
    private Order order;
}

Without Cache vs With Cache

  WITHOUT CACHE (every request hits database):
  ───────────────────────────────────────────
  1000 users view product 101
       │
       ├─ Request 1  → MySQL query → 10ms
       ├─ Request 2  → MySQL query → 10ms
       ├─ Request 3  → MySQL query → 10ms   ← same data, 1000 times!
       └─ ...1000x   → MySQL OVERLOADED 💥

  WITH REDIS CACHE:
  ──────────────────────────────────────────
  Request 1    → Cache MISS → MySQL query → store in Redis → 10ms
  Request 2    → Cache HIT  → Redis reply → 0.1ms  ✅
  Request 3    → Cache HIT  → Redis reply → 0.1ms  ✅
  ...999 more  → Cache HIT  → Redis reply → 0.1ms  ✅
  MySQL gets only 1 query instead of 1000! 🎉

Spring Cache Annotations

// ── 1. Enable caching in the app ──
@SpringBootApplication
@EnableCaching   // ← add this!
public class ProductServiceApplication { ... }

// ── 2. application.properties ──
// spring.cache.type=redis
// spring.redis.host=localhost
// spring.redis.port=6379

// ── 3. Use @Cacheable on service methods ──
@Service
public class ProductServiceImpl implements ProductService {

    @Autowired
    private ProductRepository productRepository;

    // Cache result. Key = "product::101", "product::102" etc.
    @Cacheable(value = "products", key = "#id")
    public Product getProductById(Long id) {
        System.out.println(">>> HIT DATABASE for product " + id); // only prints on cache miss
        return productRepository.findById(id)
            .orElseThrow(() -> new ProductNotFoundException(id));
    }

    // Cache all products
    @Cacheable(value = "all-products")
    public List<Product> getAllProducts() {
        return productRepository.findAll();
    }

    // When product is updated → delete the cache (stale data)
    @CacheEvict(value = "products", key = "#id")
    public Product updateProduct(Long id, Product updated) {
        // ... update logic
    }

    // When product is deleted → remove from cache too
    @CacheEvict(value = "products", key = "#id")
    public void deleteProduct(Long id) {
        productRepository.deleteById(id);
    }

    // Update the cache instead of deleting
    @CachePut(value = "products", key = "#product.id")
    public Product createProduct(Product product) {
        return productRepository.save(product);
    }
}

TTL — Cache Expiry

// Set Time-To-Live on cached data
@Configuration
@EnableCaching
public class RedisConfig {

    @Bean
    public RedisCacheManager cacheManager(RedisConnectionFactory factory) {
        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
            .entryTtl(Duration.ofMinutes(10))   // cache expires in 10 minutes
            .serializeValuesWith(
                RedisSerializationContext.SerializationPair
                    .fromSerializer(new GenericJackson2JsonRedisSerializer())
            );

        return RedisCacheManager.builder(factory)
            .cacheDefaults(config)
            .withCacheConfiguration("products",        // product cache: 10 min
                config.entryTtl(Duration.ofMinutes(10)))
            .withCacheConfiguration("all-products",    // all-products cache: 5 min
                config.entryTtl(Duration.ofMinutes(5)))
            .build();
    }
}

The Problem Key Vault Solves

  ❌ WRONG — password visible in code/GitHub:
  ─────────────────────────────────────────────────
  spring.datasource.password=MyDB@Pass123!   ← exposed!
  azure.servicebus.connection-string=Endpoint=sb://...SharedAccessKey=abc123  ← exposed!

  ✅ RIGHT — secrets stored in Azure Key Vault:
  ─────────────────────────────────────────────────
  application.properties: (safe to commit)
  spring.datasource.password=${shopease-db-password}

  Azure Key Vault:
  ┌───────────────────────────────────┐
  │  Secret Name           │ Value    │
  │  shopease-db-password  │ ****     │  ← encrypted, access-controlled
  │  shopease-db-username  │ ****     │
  │  shopease-sb-conn-str  │ ****     │
  └───────────────────────────────────┘
  At startup → Spring fetches secrets from Key Vault → injects into app

Setup (Maven Dependency)

// pom.xml
<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter-keyvault-secrets</artifactId>
</dependency>

application.properties (safe to commit)

# Azure Key Vault config
spring.cloud.azure.keyvault.secret.endpoint=https://shopease-vault.vault.azure.net/
spring.cloud.azure.keyvault.secret.property-sources[0].endpoint=https://shopease-vault.vault.azure.net/

# These values are FETCHED FROM KEY VAULT at startup:
# Secret name in Key Vault      → property name here
# shopease-db-password     →  spring.datasource.password
# shopease-db-username     →  spring.datasource.username
# shopease-redis-password  →  spring.redis.password

spring.datasource.url=jdbc:mysql://shopease-db.mysql.database.azure.com:3306/products
spring.datasource.username=${shopease-db-username}       # Key Vault fetches this
spring.datasource.password=${shopease-db-password}       # Key Vault fetches this

How Authentication Works (Managed Identity)

// In Azure, your app (running on App Service / Container App) gets a
// "Managed Identity" — a built-in identity that Azure trusts.
// No credentials needed! Azure automatically authenticates your app to Key Vault.

// application.properties
spring.cloud.azure.credential.managed-identity-enabled=true

// OR for local development (using your Azure CLI login):
// Run: az login  — then Spring uses your account automatically

// ── Programmatic access (when needed) ──
@Service
public class SecretService {
    @Value("${shopease-db-password}")  // Spring injects Key Vault secret!
    private String dbPassword;

    // You can also use SecretClient directly:
    @Autowired
    private SecretClient secretClient;

    public String getSecret(String secretName) {
        KeyVaultSecret secret = secretClient.getSecret(secretName);
        return secret.getValue();
    }
}

Synchronous vs Asynchronous

  ❌ SYNCHRONOUS (tightly coupled):
  ──────────────────────────────────────────
  OrderService → directly calls → NotificationService
  - If Notification is down → Order FAILS  ❌
  - Order waits for email to be sent        ❌
  - Slow email server = slow order API      ❌

  ✅ ASYNCHRONOUS (loosely coupled via Service Bus):
  ──────────────────────────────────────────────────
  OrderService                   NotificationService
       │                                │
       │  1. Save order to DB           │
       │  2. Drop msg to Service Bus    │
       │  3. Return 201 Created ✅       │
       │                                │
       │  Service Bus Queue             │
       │  [OrderPlacedEvent]─────────▶  │  4. Pick up message
       │                                │  5. Send email
       │                                │  (even if delayed - it will happen)

Queue vs Topic

Setup

// pom.xml
<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter-servicebus-jms</artifactId>
</dependency>

// application.properties
spring.jms.servicebus.connection-string=${shopease-sb-connection-string}  // from Key Vault!
spring.jms.servicebus.pricing-tier=standard

Publisher — Order Service sends event

// ── Event class (message payload) ──
public class OrderPlacedEvent {
    private Long orderId;
    private String userId;
    private String customerEmail;
    private double totalAmount;
    private String productName;
    private LocalDateTime placedAt;
    // constructor + getters
}

// ── Publisher ──
@Service
public class OrderEventPublisher {

    @Autowired
    private JmsTemplate jmsTemplate;

    public void publishOrderPlaced(Order order) {
        OrderPlacedEvent event = new OrderPlacedEvent(
            order.getId(),
            order.getUserId(),
            order.getCustomerEmail(),
            order.getTotalAmount(),
            order.getProductName(),
            LocalDateTime.now()
        );

        jmsTemplate.convertAndSend("order-placed-queue", event);
        // Message is now in Azure Service Bus queue ✅
        System.out.println("Published OrderPlacedEvent for order: " + order.getId());
    }
}

// ── In OrderService.placeOrder() ──
@Service
public class OrderService {
    @Autowired private OrderRepository orderRepository;
    @Autowired private OrderEventPublisher eventPublisher;

    public Order placeOrder(OrderRequest request) {
        Order order = new Order(/*...*/);
        Order saved = orderRepository.save(order);  // 1. save

        eventPublisher.publishOrderPlaced(saved);   // 2. publish event

        return saved;                                // 3. return immediately
        // Notification Service will send email asynchronously
    }
}

Subscriber — Notification Service listens

// ── Listener in Notification Service ──
@Service
public class OrderEventListener {

    @Autowired
    private EmailService emailService;

    @JmsListener(destination = "order-placed-queue")
    public void onOrderPlaced(OrderPlacedEvent event) {
        // This method is called whenever a new message arrives in the queue

        System.out.println("Received order event for order: " + event.getOrderId());

        // Send confirmation email
        emailService.sendOrderConfirmation(
            event.getCustomerEmail(),
            event.getOrderId(),
            event.getTotalAmount()
        );

        System.out.println("Email sent to " + event.getCustomerEmail());
    }
}

// ── Email Service ──
@Service
public class EmailService {
    public void sendOrderConfirmation(String email, Long orderId, double amount) {
        // send email via SMTP / SendGrid / SES
        System.out.println("Sending email to: " + email);
        System.out.println("Your order #" + orderId + " of ₹" + amount + " is confirmed!");
    }
}