Architectural Patterns

public interface PaymentGateway {          // an abstraction the domain owns (DIP, ISP)

    PaymentResult charge(OrderId orderId, Money amount);
}

@Service
public class OrderService {

    private final PaymentGateway paymentGateway;   // constructor-injected interface, not an implementation

    public OrderService(PaymentGateway paymentGateway) {
        this.paymentGateway = paymentGateway;
    }
}

// inbound port: what the outside world calls into the domain through
public interface PlaceOrderUseCase {
    OrderId placeOrder(PlaceOrderCommand command);
}

// outbound port: what the domain calls out through -- it knows nothing about JPA
public interface OrderRepository {
    void save(Order order);
    Optional<Order> findById(OrderId id);
}

// domain service implementing the inbound port, depending only on the outbound port
@Service
public class OrderDomainService implements PlaceOrderUseCase {

    private final OrderRepository orders;   // outbound port, not a JPA type

    public OrderDomainService(OrderRepository orders) {
        this.orders = orders;
    }

    @Override
    public OrderId placeOrder(PlaceOrderCommand command) {
        Order order = Order.create(command);
        orders.save(order);
        return order.id();
    }
}

// inbound adapter: translates HTTP into a call on the inbound port
@RestController
@RequestMapping("/orders")
public class OrderController {

    private final PlaceOrderUseCase placeOrder;

    public OrderController(PlaceOrderUseCase placeOrder) {
        this.placeOrder = placeOrder;
    }

    @PostMapping
    public ResponseEntity<OrderId> create(@RequestBody PlaceOrderRequest request) {
        OrderId id = placeOrder.placeOrder(request.toCommand());
        return ResponseEntity.ok(id);
    }
}

// outbound adapter: implements the outbound port using JPA
@Repository
public class JpaOrderRepository implements OrderRepository {

    private final SpringDataOrderRepository springDataRepository;   // the actual JpaRepository

    public JpaOrderRepository(SpringDataOrderRepository springDataRepository) {
        this.springDataRepository = springDataRepository;
    }

    @Override
    public void save(Order order) {
        springDataRepository.save(OrderEntity.fromDomain(order));
    }

    @Override
    public Optional<Order> findById(OrderId id) {
        return springDataRepository.findById(id.value()).map(OrderEntity::toDomain);
    }
}

// entity: has an identity that persists across changes to its other fields
public class Order {

    private final OrderId id;          // identity
    private OrderStatus status;        // mutable state
    private final List<OrderLine> lines;

    public static Order create(PlaceOrderCommand command) {
        Order order = new Order(OrderId.generate(), OrderStatus.PLACED, command.lines());
        order.registerEvent(new OrderPlaced(order.id));   // a domain event, see below
        return order;
    }
}

// value object: no identity, defined entirely by its attributes, and immutable
public record Money(BigDecimal amount, Currency currency) {

    public Money add(Money other) {
        if (!currency.equals(other.currency)) {
            throw new IllegalArgumentException("currency mismatch");
        }
        return new Money(amount.add(other.amount), currency);
    }
}

// aggregate: a cluster of entities/value objects treated as one consistency boundary,
// modified only through its root -- here, Order is the aggregate root for its OrderLines
public class OrderLine {
    private final ProductId productId;
    private final int quantity;
    private final Money unitPrice;
}

// domain event: a fact about something that already happened inside the domain
public record OrderPlaced(OrderId orderId) {
}

@Entity
@Table(name = "order_outbox")
public class OutboxEntry {

    @Id
    @GeneratedValue
    private Long id;
    private String aggregateId;
    private String eventType;
    @Lob
    private String payload;          // the event, serialized (e.g. as JSON)
    private boolean published = false;
}

@Service
public class OrderDomainService implements PlaceOrderUseCase {

    private final OrderRepository orders;
    private final OutboxRepository outbox;

    @Transactional
    @Override
    public OrderId placeOrder(PlaceOrderCommand command) {
        Order order = Order.create(command);
        orders.save(order);                                  // business write
        outbox.save(OutboxEntry.forEvent(new OrderPlaced(order.id())));   // outbox write -- SAME transaction
        return order.id();
    }
}

// a separate relay, e.g. a @Scheduled poller (see backend/springboot/scheduling-and-shedlock.adoc)
@Component
public class OutboxRelay {

    @Scheduled(fixedDelay = 1000)
    @SchedulerLock(name = "outboxRelay", lockAtMostFor = "PT1M")
    @Transactional
    public void relay() {
        outbox.findUnpublished().forEach(entry -> {
            kafkaTemplate.send("orders", entry.getAggregateId(), entry.getPayload());
            entry.markPublished();
        });
    }
}