System Design & Architecture

// Email Service consumes event
@Service
public class OrderNotificationHandler {

    @KafkaListener(topics = "orders.placed", groupId = "email-service")
    public void handleOrderPlaced(OrderPlacedEvent event) {
        Customer customer = customerService.getById(event.customerId());
        emailService.sendOrderConfirmation(customer.getEmail(), event);
    }
}

// Inventory Service consumes same event (fan-out)
@Service
public class InventoryHandler {

    @KafkaListener(topics = "orders.placed", groupId = "inventory-service")
    public void handleOrderPlaced(OrderPlacedEvent event) {
        for (OrderItem item : event.items()) {
            inventoryService.decrementStock(item.productId(), item.quantity());
        }
    }
}

// Benefits:
// - Services are decoupled (don't know about each other)
// - Easy to add new consumers without changing producer
// - Events provide audit trail
// - Can replay events for recovery/debugging

// gRPC - schema-first with Protocol Buffers
// user.proto
/*
syntax = "proto3";

service UserService {
    rpc GetUser(GetUserRequest) returns (User);
    rpc ListUsers(ListUsersRequest) returns (stream User);  // Streaming!
}

message GetUserRequest {
    string user_id = 1;
}

message User {
    string id = 1;
    string name = 2;
    string email = 3;
}
*/

// Generated client usage
@Service
public class UserServiceGrpcClient {
    private final UserServiceGrpc.UserServiceBlockingStub stub;

    public User getUser(String userId) {
        GetUserRequest request = GetUserRequest.newBuilder()
            .setUserId(userId)
            .build();
        return stub.getUser(request);
    }

    // Streaming response
    public Iterator<User> listUsers() {
        return stub.listUsers(ListUsersRequest.getDefaultInstance());
    }
}

// gRPC advantages:
// - 10x faster than REST (binary, HTTP/2)
// - Strong typing from proto definitions
// - Bi-directional streaming
// - Auto-generated clients in any language

// Message Queue (RabbitMQ/SQS) - async, reliable
@Service
public class OrderProcessor {

    private final RabbitTemplate rabbit;

    // Send message to queue
    public void submitOrder(Order order) {
        rabbit.convertAndSend("orders.pending", order);
        // Returns immediately - processing happens async
    }
}

// Worker processes messages
@Component
public class OrderWorker {

    @RabbitListener(queues = "orders.pending")
    public void processOrder(Order order) {
        try {
            paymentService.charge(order);
            inventoryService.reserve(order);
            order.setStatus(CONFIRMED);
            orderRepository.save(order);
        } catch (Exception e) {
            // Message will be requeued (or sent to DLQ)
            throw e;
        }
    }
}

// Queue benefits:
// - Load leveling (spikes absorbed by queue)
// - Reliability (messages persisted until processed)
// - Retry with backoff (automatic requeue)
// - Dead letter queue for failed messages

// ORCHESTRATION: Central coordinator manages the saga

@Service
public class OrderSagaOrchestrator {
    private final PaymentServiceClient paymentService;
    private final InventoryServiceClient inventoryService;
    private final ShippingServiceClient shippingService;

    public void executeOrderSaga(Order order) {
        try {
            // Step 1: Payment
            PaymentResult payment = paymentService.charge(order);
            if (!payment.isSuccess()) {
                order.setStatus(PAYMENT_FAILED);
                return;
            }

            // Step 2: Reserve Inventory
            ReservationResult reservation = inventoryService.reserve(order);
            if (!reservation.isSuccess()) {
                // Compensate: refund payment
                paymentService.refund(payment.getTransactionId());
                order.setStatus(INVENTORY_FAILED);
                return;
            }

            // Step 3: Schedule Shipping
            ShippingResult shipping = shippingService.schedule(order);
            if (!shipping.isSuccess()) {
                // Compensate: release inventory, refund payment
                inventoryService.release(reservation.getReservationId());
                paymentService.refund(payment.getTransactionId());
                order.setStatus(SHIPPING_FAILED);
                return;
            }

            order.setStatus(COMPLETED);

        } catch (Exception e) {
            // Handle partial failure, trigger compensations
            handleSagaFailure(order, e);
        }
    }
}

// Orchestration pros:
// - Central place to see the flow
// - Easier to reason about
// - Simpler compensation logic

// Orchestration cons:
// - Orchestrator can become a bottleneck
// - Single point of failure
// - Tighter coupling to orchestrator

// RETRY with exponential backoff
@Service
public class ExternalServiceClient {

    @Retry(name = "externalService", fallbackMethod = "fallback")
    public Data fetchData(String id) {
        return restClient.get().uri("/data/{id}", id).retrieve().body(Data.class);
    }

    // application.yml config:
    // resilience4j.retry.instances.externalService:
    //   maxAttempts: 3
    //   waitDuration: 500ms
    //   exponentialBackoffMultiplier: 2
    //   retryExceptions:
    //     - java.io.IOException
    //     - java.net.SocketTimeoutException
}

// TIMEOUT - don't wait forever
@Service
public class SlowServiceClient {

    @TimeLimiter(name = "slowService")
    public CompletableFuture<Data> fetchSlowData(String id) {
        return CompletableFuture.supplyAsync(() -> {
            return restClient.get().uri("/slow/{id}", id).retrieve().body(Data.class);
        });
    }

    // Config: timeout after 2 seconds
    // resilience4j.timelimiter.instances.slowService:
    //   timeoutDuration: 2s
}

// Combining patterns: Retry → CircuitBreaker → TimeLimiter
@CircuitBreaker(name = "backend")
@Retry(name = "backend")
@TimeLimiter(name = "backend")
public CompletableFuture<Data> resilientCall() {
    // TimeLimiter wraps Retry wraps CircuitBreaker
}

// BULKHEAD - isolate failures, limit concurrent calls
// Prevents one slow service from consuming all threads

@Service
public class MultiServiceClient {

    // Semaphore bulkhead: limit concurrent calls
    @Bulkhead(name = "paymentService", type = Bulkhead.Type.SEMAPHORE)
    public PaymentResult charge(Order order) {
        return paymentClient.charge(order);
    }

    // Config:
    // resilience4j.bulkhead.instances.paymentService:
    //   maxConcurrentCalls: 20
    //   maxWaitDuration: 500ms

    // ThreadPool bulkhead: separate thread pool
    @Bulkhead(name = "inventoryService", type = Bulkhead.Type.THREADPOOL)
    public CompletableFuture<InventoryResult> checkInventory(String productId) {
        return CompletableFuture.supplyAsync(() -> inventoryClient.check(productId));
    }

    // Config:
    // resilience4j.thread-pool-bulkhead.instances.inventoryService:
    //   maxThreadPoolSize: 10
    //   coreThreadPoolSize: 5
    //   queueCapacity: 100
}

// Why bulkheads matter:
// Without: Slow payment service → all 200 Tomcat threads waiting → entire app unresponsive
// With: Slow payment service → only 20 threads affected → other endpoints still work

// WRITE-THROUGH: Write to cache and DB together
@Service
public class ProductService {
    public void saveProduct(Product product) {
        // Write to both synchronously
        repository.save(product);
        cache.opsForValue().set("product:" + product.getId(), product);
        // Pros: Cache always consistent
        // Cons: Slower writes, both must succeed
    }
}

// WRITE-BEHIND (Write-Back): Write to cache, async to DB
@Service
public class ProductService {
    private final BlockingQueue<Product> writeQueue = new LinkedBlockingQueue<>();

    public void saveProduct(Product product) {
        // Write to cache immediately
        cache.opsForValue().set("product:" + product.getId(), product);
        // Queue for async DB write
        writeQueue.offer(product);
        // Pros: Fast writes
        // Cons: Risk of data loss if crash before DB write
    }

    @Scheduled(fixedDelay = 1000)
    public void flushToDatabase() {
        List<Product> batch = new ArrayList<>();
        writeQueue.drainTo(batch, 100);
        if (!batch.isEmpty()) {
            repository.saveAll(batch);
        }
    }
}

// CACHE INVALIDATION STRATEGIES
// 1. TTL (Time To Live) - cache expires after duration
// 2. Event-driven - invalidate on data change events
// 3. Version-based - include version in cache key

// "There are only two hard things in CS:
//  cache invalidation and naming things."

// API VERSIONING strategies

// 1. URL path (most common, explicit)
/api/v1/users
/api/v2/users

// 2. Header (cleaner URLs, harder to test)
Accept: application/vnd.myapi.v2+json

// 3. Query param (easy to use, pollutes URL)
/api/users?version=2

@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 {
    // V1 implementation
}

@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 {
    // V2 with breaking changes
}

// PAGINATION (cursor-based is better for large datasets)
// Offset-based (simple, but slow for large offsets)
GET /orders?offset=1000&limit=20

// Cursor-based (consistent, performant)
GET /orders?cursor=eyJpZCI6MTIzfQ&limit=20

public record PagedResponse<T>(
    List<T> data,
    String nextCursor,
    boolean hasMore
) {}

// IDEMPOTENCY (safe retries)
// Client sends unique key, server deduplicates
POST /orders
Idempotency-Key: abc-123-unique

@PostMapping("/orders")
public Order createOrder(
    @RequestHeader("Idempotency-Key") String idempotencyKey,
    @RequestBody CreateOrderRequest request
) {
    // Check if already processed
    return idempotencyService.executeOnce(idempotencyKey, () -> {
        return orderService.create(request);
    });
}