Clean Architecture: Stop Writing Code That Dies When the Database Changes

// io.thecodeforge — System Design tutorial

// Domain layer: defines the port
public interface OrderRepository {
    Order findById(OrderId id);
    void save(Order order);
}

// Use case: depends on abstraction, not implementation
public class SubmitOrderUseCase {
    private final OrderRepository repo;
    private final PaymentGateway paymentGateway;

    public SubmitOrderUseCase(OrderRepository repo, PaymentGateway paymentGateway) {
        this.repo = repo;
        this.paymentGateway = paymentGateway;
    }

    public void execute(Order order) {
        // Business logic: validate, calculate total, etc.
        paymentGateway.charge(order.getTotal());
        repo.save(order);
    }
}

// Infrastructure layer: implements the port
public class PostgresOrderRepository implements OrderRepository {
    private final DataSource dataSource;

    @Override
    public Order findById(OrderId id) {
        // SQL query here
    }

    @Override
    public void save(Order order) {
        // SQL insert/update here
    }
}

// io.thecodeforge — System Design tutorial

// Domain entity — no annotations, no framework imports
public class Order {
    private OrderId id;
    private Money total;
    private OrderStatus status;

    public void submit() {
        // Business rules: validate, calculate, etc.
        this.status = OrderStatus.SUBMITTED;
    }
}

// Use case — orchestrates domain logic
public class SubmitOrderUseCase {
    private final OrderRepository repo;
    private final PaymentGateway paymentGateway;

    public void execute(Order order) {
        order.submit();
        paymentGateway.charge(order.getTotal());
        repo.save(order);
    }
}

// Interface adapter — maps HTTP request to domain
@Controller
public class OrderController {
    private final SubmitOrderUseCase useCase;

    @PostMapping("/orders")
    public ResponseEntity<Void> submitOrder(@RequestBody OrderRequest request) {
        Order order = new Order(request.getItems());
        useCase.execute(order);
        return ResponseEntity.ok().build();
    }
}

// io.thecodeforge — System Design tutorial

// Domain
public class Cart {
    private List<Item> items;
    public Money calculateTotal() { /* ... */ }
}

public interface PaymentGateway {
    PaymentResult charge(Money amount);
}

public interface InventoryService {
    boolean isInStock(Item item, int quantity);
}

// Use case
public class CheckoutUseCase {
    private final PaymentGateway paymentGateway;
    private final InventoryService inventoryService;
    private final OrderRepository orderRepository;

    public Order execute(Cart cart) {
        for (Item item : cart.getItems()) {
            if (!inventoryService.isInStock(item, 1)) {
                throw new OutOfStockException(item);
            }
        }
        Money total = cart.calculateTotal();
        PaymentResult result = paymentGateway.charge(total);
        Order order = new Order(cart, result);
        orderRepository.save(order);
        return order;
    }
}

// Infrastructure
public class StripePaymentGateway implements PaymentGateway {
    @Override
    public PaymentResult charge(Money amount) {
        // Stripe SDK calls
    }
}

public class PostgresInventoryService implements InventoryService {
    @Override
    public boolean isInStock(Item item, int quantity) {
        // SQL query
    }
}

// io.thecodeforge — System Design tutorial

// Don't do this for a simple utility
public interface StringUtils {
    String capitalize(String s);
}

public class SimpleStringUtils implements StringUtils {
    @Override
    public String capitalize(String s) {
        return s.substring(0, 1).toUpperCase() + s.substring(1);
    }
}

// Just use a static method or a simple class. No need for abstraction.

// io.thecodeforge — System Design tutorial

@Test
public void checkout_should_charge_and_save_order() {
    // Given
    PaymentGateway paymentGateway = mock(PaymentGateway.class);
    InventoryService inventoryService = mock(InventoryService.class);
    OrderRepository orderRepository = mock(OrderRepository.class);
    CheckoutUseCase useCase = new CheckoutUseCase(paymentGateway, inventoryService, orderRepository);
    Cart cart = new Cart(List.of(new Item("SKU123", 1)));
    when(inventoryService.isInStock(any(), anyInt())).thenReturn(true);
    when(paymentGateway.charge(any())).thenReturn(new PaymentResult(true, "txn_123"));

    // When
    Order order = useCase.execute(cart);

    // Then
    verify(paymentGateway).charge(any());
    verify(orderRepository).save(any());
    assertEquals(OrderStatus.SUBMITTED, order.getStatus());
}

// io.thecodeforge — System Design tutorial

// Domain entity — no annotations
public class Order {
    private OrderId id;
    private Money total;
    private OrderStatus status;
}

// Infrastructure entity — JPA annotated
@Entity
@Table(name = "orders")
public class OrderJpaEntity {
    @Id
    private UUID id;
    private BigDecimal total;
    private String status;

    public Order toDomain() {
        return new Order(new OrderId(id), new Money(total), OrderStatus.valueOf(status));
    }

    public static OrderJpaEntity fromDomain(Order order) {
        OrderJpaEntity entity = new OrderJpaEntity();
        entity.id = order.getId().getValue();
        entity.total = order.getTotal().getAmount();
        entity.status = order.getStatus().name();
        return entity;
    }
}

// io.thecodeforge — System Design tutorial

// Domain interface for logging
public interface Logger {
    void info(String message);
    void error(String message, Throwable t);
}

// Use case uses it
public class CheckoutUseCase {
    private final Logger logger;

    public void execute(Cart cart) {
        logger.info("Starting checkout for cart: " + cart.getId());
        // ...
    }
}

// Infrastructure implementation
public class Slf4jLogger implements Logger {
    private final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(Slf4jLogger.class);

    @Override
    public void info(String message) {
        log.info(message);
    }
}