Advanced Spring Boot
Architecture

src/main/java/com/company/app/
├── domain/                          ← Core business objects (no Spring deps)
│   ├── model/
│   │   ├── Order.java               (pure Java, not a JPA entity)
│   │   ├── OrderItem.java
│   │   └── Money.java               (value object)
│   ├── repository/
│   │   └── OrderRepository.java     (interface — no implementation here)
│   └── service/
│       └── OrderPricingService.java (domain service — pure business logic)
│
├── application/                     ← Use cases / orchestration
│   ├── usecase/
│   │   ├── CreateOrderUseCase.java
│   │   ├── CancelOrderUseCase.java
│   │   └── GetOrderUseCase.java
│   └── port/
│       ├── in/                      (input ports — what the app can do)
│       │   └── CreateOrderCommand.java
│       └── out/                     (output ports — what the app needs)
│           ├── SaveOrderPort.java
│           └── LoadOrderPort.java
│
├── adapter/                         ← Infrastructure details
│   ├── in/
│   │   └── web/
│   │       ├── OrderController.java     (@RestController)
│   │       └── OrderRequest.java        (web DTO)
│   └── out/
│       ├── persistence/
│       │   ├── OrderJpaEntity.java      (@Entity — JPA detail)
│       │   ├── OrderJpaRepository.java  (Spring Data)
│       │   └── OrderPersistenceAdapter.java (implements SaveOrderPort)
│       └── messaging/
│           └── KafkaOrderEventAdapter.java

// Output port — defined in application layer, implemented in adapter layer
public interface SaveOrderPort {
    Order save(Order order);
}

// Input port (use case interface)
public interface CreateOrderUseCase {
    Order createOrder(CreateOrderCommand command);
}

// Use case implementation — depends only on port interfaces, not Spring JPA
@Service
@RequiredArgsConstructor
@Transactional
public class CreateOrderService implements CreateOrderUseCase {

    private final LoadProductPort loadProduct;    // implemented by JPA adapter
    private final SaveOrderPort saveOrder;         // implemented by JPA adapter
    private final SendOrderConfirmationPort notify; // implemented by email adapter

    @Override
    public Order createOrder(CreateOrderCommand cmd) {
        // Pure business logic — no Spring, no JPA, no HTTP concerns
        List<OrderItem> items = cmd.getItems().stream()
            .map(i -> {
                Product product = loadProduct.loadById(i.getProductId())
                    .orElseThrow(() -> new ProductNotFoundException(i.getProductId()));
                return new OrderItem(product, i.getQuantity());
            })
            .toList();

        Order order = Order.create(cmd.getCustomerId(), items);
        Order saved = saveOrder.save(order);
        notify.sendConfirmation(saved);
        return saved;
    }
}

// Adapter — bridges Spring Data JPA to the domain port
@Component
@RequiredArgsConstructor
public class OrderPersistenceAdapter implements SaveOrderPort, LoadOrderPort {

    private final OrderJpaRepository jpaRepo;
    private final OrderMapper mapper;

    @Override
    public Order save(Order order) {
        OrderJpaEntity entity = mapper.toEntity(order);
        return mapper.toDomain(jpaRepo.save(entity));
    }
}

// Value Object — immutable, no identity
public record Money(BigDecimal amount, String currency) {
    public Money {
        if (amount.compareTo(BigDecimal.ZERO) < 0)
            throw new IllegalArgumentException("Amount cannot be negative");
    }
    public Money add(Money other) {
        if (!this.currency.equals(other.currency))
            throw new IllegalArgumentException("Currency mismatch");
        return new Money(this.amount.add(other.amount), this.currency);
    }
}

// Aggregate Root — controls access to its children
public class Order {
    private final OrderId id;
    private final CustomerId customerId;
    private OrderStatus status;
    private final List<OrderItem> items = new ArrayList<>();
    private final List<DomainEvent> domainEvents = new ArrayList<>();

    // Factory method — enforces invariants
    public static Order create(CustomerId customerId, List<OrderItem> items) {
        if (items.isEmpty()) throw new IllegalArgumentException("Order must have items");
        Order order = new Order(OrderId.generate(), customerId, OrderStatus.PENDING);
        items.forEach(order.items::add);
        // Register domain event — published AFTER the transaction commits
        order.domainEvents.add(new OrderCreatedEvent(order.id, customerId, items));
        return order;
    }

    public void confirm() {
        if (this.status != OrderStatus.PENDING)
            throw new IllegalStateException("Only PENDING orders can be confirmed");
        this.status = OrderStatus.CONFIRMED;
        domainEvents.add(new OrderConfirmedEvent(this.id));
    }

    public void cancel(String reason) {
        if (this.status == OrderStatus.SHIPPED)
            throw new IllegalStateException("Cannot cancel a shipped order");
        this.status = OrderStatus.CANCELLED;
        domainEvents.add(new OrderCancelledEvent(this.id, reason));
    }

    public Money totalAmount() {
        return items.stream()
            .map(item -> item.unitPrice().multiply(item.quantity()))
            .reduce(new Money(BigDecimal.ZERO, "USD"), Money::add);
    }

    // Spring Data auto-publishes via AbstractAggregateRoot
    public List<DomainEvent> popDomainEvents() {
        List<DomainEvent> events = List.copyOf(domainEvents);
        domainEvents.clear();
        return events;
    }
}

// ── WRITE SIDE ──
// Command — immutable, describes intent
public record CreateOrderCommand(
    CustomerId customerId,
    List<CreateOrderCommand.Item> items
) {
    public record Item(ProductId productId, int quantity) {}
}

@Service
@RequiredArgsConstructor
public class CreateOrderCommandHandler {
    private final OrderRepository orderRepo;

    @Transactional
    public OrderId handle(CreateOrderCommand cmd) {
        // Load, validate, persist aggregate
        Order order = Order.create(cmd.customerId(), buildItems(cmd));
        orderRepo.save(order);
        return order.getId();
    }
}

// ── READ SIDE ──
// Flat projection — optimized for display
public record OrderSummaryDto(
    String orderId,
    String customerEmail,
    String status,
    BigDecimal totalAmount,
    int itemCount,
    LocalDateTime createdAt
) {}

// Read model — can use native SQL, views, or a separate read DB
@Repository
public interface OrderSummaryRepository extends JpaRepository<OrderSummaryView, String> {
    @Query(value = """
        SELECT o.id, u.email, o.status,
               SUM(oi.unit_price * oi.quantity) as total,
               COUNT(oi.id) as item_count,
               o.created_at
        FROM orders o
        JOIN users u ON o.customer_id = u.id
        JOIN order_items oi ON o.id = oi.order_id
        WHERE o.customer_id = :customerId
        GROUP BY o.id, u.email, o.status, o.created_at
        ORDER BY o.created_at DESC
        """, nativeQuery = true)
    List<OrderSummaryDto> findSummariesByCustomer(String customerId);
}

// Domain event
public record OrderPlacedEvent(String orderId, String customerId,
                                BigDecimal total, Instant occurredAt) {}

// Publisher — in the command handler or aggregate
@Service
@RequiredArgsConstructor
public class OrderService {
    private final ApplicationEventPublisher eventPublisher;

    @Transactional
    public Order placeOrder(PlaceOrderRequest req) {
        Order order = processOrder(req);
        // Published AFTER transaction commits — use @TransactionalEventListener
        eventPublisher.publishEvent(
            new OrderPlacedEvent(order.getId(), order.getCustomerId(),
                                 order.getTotal(), Instant.now()));
        return order;
    }
}

// Listener — @TransactionalEventListener fires AFTER the publishing transaction commits
@Component
public class OrderEventHandlers {

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    @Async  // don't slow down the order transaction
    public void onOrderPlaced(OrderPlacedEvent event) {
        // Now it's safe to send email — order is definitely in the DB
        emailService.sendOrderConfirmation(event.customerId(), event.orderId());
    }

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    @Async
    public void updateAnalytics(OrderPlacedEvent event) {
        analyticsService.recordSale(event.total());
    }
}

// Outbox event entity
@Entity
@Table(name = "outbox_events")
public class OutboxEvent {
    @Id private String id = UUID.randomUUID().toString();
    private String aggregateType;   // "ORDER"
    private String aggregateId;     // orderId
    private String eventType;       // "OrderPlacedEvent"
    private String payload;         // JSON
    private boolean published = false;
    private Instant createdAt = Instant.now();
}

// Write to outbox IN THE SAME TRANSACTION as the domain write
@Transactional
public Order placeOrder(PlaceOrderRequest req) {
    Order order = processOrder(req);
    orderRepo.save(order);

    // Atomically write the outbox event — same transaction, same DB
    outboxRepo.save(new OutboxEvent("ORDER", order.getId(),
        "OrderPlacedEvent", toJson(order)));

    return order;  // transaction commits both order AND outbox entry
}

// Separate polling job — reads unprocessed outbox events and publishes to Kafka
@Scheduled(fixedDelay = 1000)
@Transactional
public void processOutbox() {
    List<OutboxEvent> pending = outboxRepo.findByPublishedFalse();
    for (OutboxEvent event : pending) {
        kafkaTemplate.send(event.getEventType(), event.getPayload());
        event.setPublished(true);
    }
    // Even if Kafka publish fails, outbox row is not marked published
    // — will be retried on next poll
}

// pom.xml dependency
// spring-cloud-starter-gateway

// application.yml — declarative routing
spring:
  cloud:
    gateway:
      routes:
        - id: order-service
          uri: lb://order-service    // lb:// = load-balanced via Eureka
          predicates:
            - Path=/api/orders/**
          filters:
            - RewritePath=/api/orders/(?<path>.*), /${path}
            - name: CircuitBreaker
              args:
                name: orderService
                fallbackUri: forward:/fallback/orders
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 100
                redis-rate-limiter.burstCapacity: 200

        - id: product-service
          uri: lb://product-service
          predicates:
            - Path=/api/products/**

      default-filters:
        - AddResponseHeader=X-Gateway-Version, 1.0
        - name: Retry
          args:
            retries: 3
            statuses: BAD_GATEWAY, SERVICE_UNAVAILABLE

// pom.xml: spring-boot-starter-aop + resilience4j-spring-boot3

// application.yml
resilience4j:
  circuitbreaker:
    instances:
      inventoryService:
        sliding-window-size: 10
        failure-rate-threshold: 50        # open after 50% failures
        wait-duration-in-open-state: 10s
        permitted-number-of-calls-in-half-open-state: 3
        slow-call-duration-threshold: 2s  # calls > 2s count as failures
        slow-call-rate-threshold: 80

  retry:
    instances:
      inventoryService:
        max-attempts: 3
        wait-duration: 500ms
        retry-exceptions:
          - java.net.ConnectException
          - java.util.concurrent.TimeoutException

  timelimiter:
    instances:
      inventoryService:
        timeout-duration: 3s

---
@Service
public class InventoryService {

    @CircuitBreaker(name = "inventoryService", fallbackMethod = "getStockFallback")
    @Retry(name = "inventoryService")
    @TimeLimiter(name = "inventoryService")
    public CompletableFuture<Integer> getStockLevel(String productId) {
        return CompletableFuture.supplyAsync(() ->
            inventoryClient.getStock(productId));
    }

    // Fallback — called when circuit is OPEN or all retries exhausted
    public CompletableFuture<Integer> getStockFallback(String productId, Exception ex) {
        log.warn("Inventory service unavailable for {}: {}", productId, ex.getMessage());
        return CompletableFuture.completedFuture(-1);  // -1 = unknown stock
    }
}

// Monitoring — Resilience4j exposes Actuator endpoints
// GET /actuator/circuitbreakers  → state of all circuit breakers
// GET /actuator/retryevents      → retry statistics

// Without bulkhead: one slow service exhausts the shared thread pool
// With bulkhead: each service gets its own isolated thread pool

resilience4j:
  bulkhead:
    instances:
      paymentService:
        max-concurrent-calls: 10       # max 10 parallel calls
        max-wait-duration: 100ms       # fail fast if no thread available

@CircuitBreaker(name = "paymentService")
@Bulkhead(name = "paymentService", type = Bulkhead.Type.THREADPOOL)
public CompletableFuture<PaymentResult> processPayment(PaymentRequest req) {
    return CompletableFuture.supplyAsync(() -> paymentGateway.charge(req));
    // Runs in the paymentService thread pool — can't starve other services
}

// pom.xml
// spring-boot-starter-actuator
// micrometer-tracing-bridge-otel (OpenTelemetry bridge)
// opentelemetry-exporter-zipkin

// application.yml
management:
  tracing:
    sampling:
      probability: 1.0  # trace 100% of requests (use 0.1 in production)
  zipkin:
    tracing:
      endpoint: http://zipkin:9411/api/v2/spans

// Spring Boot 3 auto-configures tracing — no code changes needed.
// Every incoming HTTP request gets a traceId + spanId added to MDC.
// RestClient / WebClient automatically propagate the trace headers.

// Manual span creation for important operations
@Service
@RequiredArgsConstructor
public class InventoryCheckService {
    private final Tracer tracer;

    public boolean checkAvailability(String productId) {
        Span span = tracer.nextSpan().name("inventory.check").start();
        try (Tracer.SpanInScope ws = tracer.withSpan(span)) {
            span.tag("product.id", productId);
            boolean available = inventoryRepo.isAvailable(productId);
            span.tag("available", String.valueOf(available));
            return available;
        } catch (Exception e) {
            span.error(e);
            throw e;
        } finally {
            span.end();
        }
    }
}