Register for free

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

You’ve split your application into one class per use case.

Then you gave every use case the same interface — the Command Handler pattern:

public interface UseCase<TRequest, TResponse> {
    Result<TResponse, UseCaseError> execute(TRequest request);
}

One request in. One result out.

But you run into issues:

❗Problem #1: Cross-cutting concerns duplicated across use cases

Logging, transactions, authorization — many use cases need them, so you end up copying them into each one:

public final class PlaceOrder
        implements UseCase<PlaceOrderRequest, PlaceOrderResponse> {

    public Result<PlaceOrderResponse, UseCaseError> execute(
        PlaceOrderRequest request
    ) {
        log.info("PlaceOrder started");
        authorize(Permission.PLACE_ORDER);
        return transactional(() -> {
            // ... the actual use case logic
        });
    }
}

public final class CancelOrder
        implements UseCase<CancelOrderRequest, CancelOrderResponse> {

    public Result<CancelOrderResponse, UseCaseError> execute(
        CancelOrderRequest request
    ) {
        log.info("CancelOrder started");
        authorize(Permission.CANCEL_ORDER);
        return transactional(() -> {
            // ... the actual use case logic
        });
    }
}

The same lines repeat in many use cases, and every new use case has to remember them.

❗Problem #2 (secondary): Constructors with lots of injection

Every use case is its own class, so every controller needs each one it calls injected:

public OrderController(
    PlaceOrder placeOrder,
    ViewOrderDetails viewOrderDetails,
    CancelOrder cancelOrder,
    PublishCoupon publishCoupon,
    BrowseCoupons browseCoupons,
    // ... and more with every new use case
) { ... }

And each endpoint calls its own use case directly:

@PostMapping("/orders")
public ResponseEntity<?> placeOrder(@RequestBody PlaceOrderRequest request) {
    return mapResult(placeOrder.execute(request));
}

The constructor grows with every use case you add. The wiring becomes noise, and every controller test has to supply them all.

❌ Poor Solution: Base Classes

The tempting fix for Problem #1 is a BaseUseCase that every use case extends. But as it grows with logging, authorization, transactions, and error handling, every use case inherits all of it — whether it needs it or not.

And it does nothing for Problem #2: the controller still needs every use case injected.

✅ Effective Solution: Command Bus — in Practice

Read more

Let's talk

📅 Join our next live course: ATDD, Clean Architecture, Pipelines
Early bird: €100 off with code EARLYBIRD100

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

Your SubscriptionService has 800 lines.

It activates subscriptions, handles cancellations, validates plan changes, checks expiration...

Meanwhile Subscription is just getters and setters.

That’s the problem.

❌Your Domain Is Just Data (Anemic Domain)

public class Subscription {
    private String customerId;
    private SubscriptionPlan plan;
    private SubscriptionStatus status;
    private LocalDate startedAt;
    private LocalDate expiresAt;
    private BigDecimal price;

    public String getCustomerId() {
        return customerId;
    }

    public void setCustomerId(String customerId) {
        this.customerId = customerId;
    }

    public SubscriptionPlan getPlan() { ... }

    public void setPlan(SubscriptionPlan plan) { ... }

    public SubscriptionStatus getStatus() { ... }

    public void setStatus(SubscriptionStatus status) { ... }

    public LocalDate getStartedAt() { ... }

    public void setStartedAt(LocalDate startedAt) { ... }

    public LocalDate getExpiresAt() { ... }

    public void setExpiresAt(LocalDate expiresAt) { ... }

    public BigDecimal getPrice() { ... }

    public void setPrice(BigDecimal price) { ... }
}

There isn’t much here.

The Subscription holds data.

The business rules live somewhere else:

public class SubscriptionService {

    public void cancel(Subscription subscription) {
        if (subscription.getStartedAt().plusDays(7).isBefore(LocalDate.now())) {
            throw new IllegalStateException(
                "Free cancellation is only available during the 7-day trial"
            );
        }

        subscription.setStatus(SubscriptionStatus.CANCELLED);
    }

    public void changePlan(
        Subscription subscription,
        SubscriptionPlan newPlan
    ) {
        if (newPlan == subscription.getPlan()) {
            throw new IllegalArgumentException(
                "Subscription is already on this plan"
            );
        }

        subscription.setPlan(newPlan);
        subscription.setPrice(newPlan.getPrice());
    }

    public void renew(Subscription subscription) {
        if (subscription.getStatus() != SubscriptionStatus.ACTIVE) {
            throw new IllegalStateException(
                "Only active subscriptions can be renewed"
            );
        }

        subscription.setExpiresAt(
            subscription.getExpiresAt().plusMonths(1)
        );
    }
}

At first, this doesn’t look terrible.

But keep adding business rules.

Soon you have:

SubscriptionService
├── startTrial()
├── cancel()
├── changePlan()
├── renew()
├── pause()
├── resume()
├── extendTrial()
├── changeBillingCycle()
├── updatePaymentMethod()
└── ...

And your Subscription is still just data.

That’s where the real problems appear:

• Rules get scattered across services

• The same rules get duplicated in different places

• Rules can be bypassed by calling setters directly

• Changing a business rule means hunting through services to find everywhere it is implemented

• The Subscription object can’t protect its own state

✅Your Domain Owns the Rules (Rich Domain)

Read more

Let's talk

📅 Join our next live course: ATDD, Clean Architecture, Pipelines
Early bird: €100 off with code EARLYBIRD100

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

You already know a fat service class is a bad place for all your business logic.

So you split it up.

One class per use case, like in Uncle Bob's example:

public class PlaceOrder {
    public PlaceOrderResponse placeOrder(PlaceOrderRequest request) { ... }
}

public class ViewOrderDetails {
    public ViewOrderDetailsResponse getOrder(String orderNumber) { ... }
}

public class CancelOrder {
    public void cancelOrder(String orderNumber) { ... }
}

public class PublishCoupon {
    public Coupon createCoupon(String couponCode, BigDecimal discountRate,
                                Instant validFrom, Instant validTo, Integer usageLimit) { ... }
}

public class BrowseCoupons {
    public List<Coupon> getAllCoupons() { ... }
}

Looks better.

But splitting the service into separate classes didn’t fix everything.

Here’s what’s still wrong:

❌ Entities leak across the boundary — but only sometimes

PublishCoupon returns a Coupon.

BrowseCoupons returns List<Coupon>.

But PlaceOrder and ViewOrderDetails return response DTOs.

So... can entities cross the use case boundary or not?

You can’t tell. It depends on which class you’re looking at.

❌ A bug is hiding in PublishCoupon

If you accidently swap validFrom and validTo — it still compiles, because they’re the same type.

But now your coupon has the wrong validity period — it’s backwards.

CouponController already has a PublishCouponRequest with all the values. Instead of passing that request to PublishCoupon, it pulls the values out and passes them one by one.

That's how you end up with a bug like this.

❌ Expected outcomes are thrown, not declared

Order not found, order can’t be delivered — are thrown as exceptions instead of declared.

These aren't bugs. They're things that can happen when the use case runs.

But they’re in a shared exception handler that has grown a case for every use case's failures.

The method says “I return an order.” It doesn't tell you that “order not found” or “order can't be delivered” can happen.

❌ Calling each use case is different

PlaceOrder takes a request object, ViewOrderDetails/CancelOrder take a raw String, PublishCoupon takes five loose parameters, BrowseCoupons takes nothing.

There’s no obvious answer to: “How do I call a use case?”

❌ The class says one thing, the method says another

ViewOrderDetails.getOrder()

The class says “view the order details”, but the method says “get the order.”

Same problem here: PublishCoupon.createCoupon()

The class says “publish a coupon”, but the method says “create a coupon”.

Read more

Let’s talk →

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

“What should I do when a use case fails?”

But a use case can fail for completely different reasons.

Maybe:

• the customer doesn’t exist

• the order hasn’t been paid for

• the order cannot be checked out

• the payment provider is unavailable

Should the use case handle all of them?

Error Handling at the Application layer

This layer contains your use cases:

• checkout order

• refund payment

• create shipment

• reserve seat

This is where application rules are enforced.

Examples:

• cannot checkout if another checkout is already in progress

• cannot place an order for a customer that doesn’t exist

• cannot apply the same coupon twice

These are rules that the use case needs to check because because the information isn't inside the Order itself.

E.g. an Order can’t know whether the customer exists or another checkout is already in progress, or whether a coupon had already been used. The use case can check that information.

These are not technical failures. A database connection dropping is a completely different kind of problem.

❌ Use cases should NOT handle infrastructure exceptions

public void checkout(Order order) {

    try {
        paymentGateway.charge(order);
        orderRepository.save(order);
        shippingGateway.notifyWarehouse(order);

    } catch (StripeException e) {
        throw new RuntimeException("Payment failed");
    } catch (SQLException e) {
        throw new RuntimeException("Database error");
    } catch (HttpException e) {
        throw new RuntimeException("Warehouse call failed");
    }
}

Now the use case is tied to three unrelated technologies:

• StripeException — Stripe’s SDK

• SQLException — JDBC / the database

• HttpException — the HTTP client

Swap Stripe for PayPal, JDBC for an ORM, or the HTTP client for a message queue, and you now have to change the use case too.

But the checkout rules haven’t changed.

That’s the problem.

✅ Use cases should ONLY handle application errors

Read more

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

The first rule Uncle Bob lists in The Clean Architecture is:

“Independent of Frameworks. The architecture does not depend on the existence of some library of feature laden software. This allows you to use such frameworks as tools, rather than having to cram your system into their limited constraints.”

Frameworks as tools. That’s reasonable.

But it usually gets repeated as something much stricter.

No annotations. No libraries. No framework classes.

Nothing.

The domain must be completely pure.

I disagree.

Not because frameworks should control your business logic.

They shouldn’t.

But not every framework dependency is automatically a problem.

Some dependencies genuinely make your code harder to change.

Others simply make your code easier to write.

There’s a huge difference between:

• @Service

• @Component

• @Repository

and

• @Entity

• @Id

• @Column

• @ManyToOne

The first barely affects your domain. The second fundamentally shapes it.

The strict reading treats them the same.

A class with an annotation, a service managed by Spring, a repository injected by a framework — all bad.

The result?

They end up building systems that are technically “pure” but harder to work with.

Because the goal of architecture is not to remove every dependency. It is to remove the dependencies that dictate how your business rules are written.

A framework dependency is not automatically harmful

Read more

🏆 Register now

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

How Uncle Bob writes unit tests in Clean Architecture

Years ago, I wrote unit tests in Clean Architecture the way Uncle Bob does. Unit tests target use cases and verify the stateful outcomes on repositories and gateways through test doubles.

In the Clean Coders comparative design series, Uncle Bob shows that he writes unit tests targeting use cases, not targeting the domain. That’s why for each use case class he has a corresponding unit test class - a 1:1 mapping between use cases and unit tests.

You’ll notice that even though he targets use cases and not the domain, the tests are still coupled to the domain - they assert directly on domain entities. That turns out to be a challenge, as we’ll see later in this article.

E.g. for the use case PostDocument here’s the unit test PostDocumentTest:

@Test
public void canPostAnyDocument() throws Exception {
    LocalDateTime now = LocalDateTime.now();
    Document createdDocument = postDocument.post(“username”, “text”);
    Document fetchedDocument = UseCaseContext.repository.getDocument(createdDocument.id);
    assertThat(fetchedDocument.username).isEqualTo(“username”);
    assertThat(fetchedDocument.text).isEqualTo(“text”);
    assertThat(fetchedDocument.id).isEqualTo(createdDocument.id);
    assertThat(fetchedDocument.dateTime).isEqualTo(createdDocument.dateTime);
}

Real-life example: eShop - placing orders

Now let’s illustrate Uncle Bob’s approach to unit tests on a more realistic example - the eShop.

A customer places an order. The PlaceOrder use case takes a SKU and a quantity, looks up the product, checks stock, calculates the total order price, saves the order, notifies the customer, and returns the order number. It reaches the outside world through repository interfaces and gateway interfaces.

The domain holds two entities - Order and Product - plus value objects that own invariants a primitive can’t: Quantity (must be positive), Money (currency and arithmetic), OrderNumber (the format we generate). Those repository and gateway interfaces are part of the domain too - abstractions the use case owns and depends on, implemented out at the infrastructure edge.

Unit testing the PlaceOrder use case

So when we adopt Clean Architecture, we write unit tests against the use case. The test class comes out like this:

class PlaceOrderUnitTest {

    ...

    @BeforeEach
    void setUp() {
        orderRepository = new FakeOrderRepository();
        productGateway = new StubProductGateway();
        orderNumberGateway = new StubOrderNumberGateway();
        notificationGateway = new SpyNotificationGateway();

        placeOrder = new PlaceOrder(
            orderRepository, productGateway, orderNumberGateway, notificationGateway);
    }

    @Test
    void calculatesTheTotal() {
        productGateway.willReturn(new Product(“ABC”, Money.of(20), Quantity.of(10)));
        orderNumberGateway.willReturn(OrderNumber.of(“ORD-1001”));

        var request = new PlaceOrderRequest();
        request.setSku(“ABC”);
        request.setQuantity(4);

        var result = placeOrder.execute(request);

        assertThat(result.isSuccess()).isTrue();
        var addedOrder = orderRepository.getOrder(OrderNumber.of(“ORD-1001”));
        assertThat(addedOrder.getSku()).isEqualTo(“ABC”);
        assertThat(addedOrder.getTotalPrice()).isEqualTo(Money.of(80));
    }

    @Test
    void rejectsAnOrderThatExceedsStock() {
        productGateway.willReturn(new Product(“ABC”, Money.of(20), Quantity.of(10)));

        var request = new PlaceOrderRequest();
        request.setSku(“ABC”);
        request.setQuantity(15);

        var result = placeOrder.execute(request);

        assertThat(result.isSuccess()).isFalse();
        assertThat(orderRepository.isEmpty()).isTrue();
    }

    ...
}

🚫Maintenance nightmare - refactoring the domain breaks unit tests

The tests are green. 100% code coverage, 100% mutation coverage.

But then, there comes a day when we need to refactor the domain. That’s when the nightmare starts...

Read more

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

Every few months someone declares that Clean Architecture is dead.

The new answer?

Vertical Slice Architecture.

Usually it goes something like this:

“Why should I jump between ten different files just to understand one feature? Put everything for that feature in one place.”

Instead of splitting code into controllers, use cases, domain objects and repositories...

...put everything for PlaceOrder in one place.

One handler.

One folder.

One feature.

"Everything is in one place"

This is the promise of Vertical Slice Architecture.

PlaceOrder
├── HTTP Request Validation
├── Inventory Rules
├── Discount Rules
├── Price Calculation
├── SQL Query
├── ORM Mapping
├── SAP Integration
└── HTTP Response Mapping

Finance wants to change the discount rules.

Which parts are relevant?

PlaceOrder
├── HTTP Request Validation
├── Inventory Rules
├── Discount Rules ⭐
├── Price Calculation
├── SQL Query
├── ORM Mapping
├── SAP Integration
└── HTTP Response Mapping

Only one item matters.

The rest is noise.

But to find it, you have to going through request validation, persistence, mappings and integrations that have nothing to do with discount rules.

That’s the mental overhead.

Because the business logic is mixed in with everything else.

Don’t mix different concerns

With Clean Architecture:

Presentation Layer
├── REST API Controllers
├── HTTP Request Validation
└── HTTP Response Mapping

Application Layer
├── Place Order Use Case
└── Cancel Order Use Case

Domain Layer
├── Inventory Rules
├── Discount Rules
└── Price Calculation

Infrastructure Layer
├── SQL Query
├── ORM Mapping
└── SAP Integration

There’s more files, but…

Finance wants to change the discount rules.

You immediately know where to look.

Domain Layer
├── Inventory Check
├── Discount Rules ⭐
└── Price Calculation

Done.

You don't have to mentally filter out SQL, HTTP, ORM mappings and SAP integration first.

Because the business logic is isolated.

The context you DON’T need

❌ Vertical Slice

🔍︎ Find discount rule

• Open PlaceOrder

• Scroll past request validation

• Scroll past database code

• Scroll past SAP mapping

• Finally change discount rule

✅ Clean Architecture

🔍︎ Find discount rule

• Open Domain Layer

• Change discount rule

💡Real-life Example: Ordering System

Finance doesn't just ask for one discount rule.

The rules start growing:

• Premium customers get 10% off

• Orders above €1,000 get another 5% discount

• Some products are excluded

• Discounts cannot be combined

• Regional promotions override standard discounts

Now you need to change the discount calculation.

❌ Vertical Slice Architecture

Read more

Subscribe now

Your ORM has entities.

Clean Architecture talks about entities.

They sound like the same thing.

They’re not.

❌ Your ORM Becomes Your Domain

You create an ORM entity (JPA entity) because you need to store orders.

@Entity
class Order {
    @Id
    private Long id;

    private OrderStatus status;
    private int quantity;
    private BigDecimal unitPrice;
}

And an ORM repository (JPA repository) to save and load it:

interface OrderJpaRepository extends JpaRepository<Order, Long> {
    // findById and save come out-of-the-box:
    // Optional<Order> findById(Long id);
    // Order save(Order order);
}

So far, so good.

Its job is persistence.

Then you need to place an order — and you expect an order to be in a valid state before it is saved. So you give Order a constructor that refuses to build an invalid order — e.g. one with a non-positive quantity or a null unit price:

Order(int quantity, BigDecimal unitPrice) {
    if (quantity <= 0) {
        throw new RuntimeException("quantity must be positive");
    }

    if (unitPrice == null) {
        throw new RuntimeException("unit price is required");
    }

    this.status = OrderStatus.PLACED;
    this.quantity = quantity;
    this.unitPrice = unitPrice;
}

Now an Order cannot exist in a broken state.

Your use case builds one through it:

class PlaceOrder {

    void execute(int quantity, BigDecimal unitPrice) {
        var order = new Order(quantity, unitPrice);
        orderRepository.save(order);
    }
}

And your use case depends on it.

Your ORM entity has become your domain entity.

It looks fine. It compiles. It runs.

Except — declaring that constructor removed Java’s free no-arg one. And JPA cannot live without one.

That’s worse than a plain compile error. It compiles, it starts up, and it even saves correctly — then breaks the first time someone reads the order back. Nothing warns you until then.

So you’re forced to add it back:

protected Order() {}   // required by JPA — status null, quantity 0, unitPrice null

You wrote a constructor to reject invalid orders.

JPA makes you add a no-arg one next to it — one that builds an order with a null status, zero quantity, no price.

Marking it protected doesn’t help. When Hibernate loads a row, it ignores every access modifier by using reflection: it invokes that no-arg constructor, then sets the fields one by one.

Your validating constructor never runs. Your checks never execute.

An order no business would accept — and Hibernate builds one on every load.

Here is the problem.

An object can only enforce its invariants in one place: its constructor. JPA bypasses it — it forces a no-arg constructor, then sets the fields by reflection, skipping your real constructor on every load.

So the real problem is not that “your domain is coupled.”

It’s this:

This entity cannot guarantee it's always valid (enforce business rules).

Your validation only runs when you call the constructor yourself. JPA never calls it — on every load it constructs the object empty and sets the fields directly.

And every transition you validate later — cancel, ship, and so on — then runs on an object that was never validated in the first place.

The code compiles, it runs, and every invariant you thought you wrote is optional.

And it doesn’t stop at Order.

Use a Money value object instead of BigDecimal — immutable, always valid, exactly what DDD wants:

final class Money {
    private final BigDecimal amount;

    Money(BigDecimal amount) {
        if (amount == null) {
            throw new RuntimeException("amount is required");
        }

        this.amount = amount;
    }
}

To persist it, JPA needs it as @Embeddable. And @Embeddable demands the same price: drop final, add a no-arg constructor.

@Embeddable
class Money {                    // no longer final
    private BigDecimal amount;   // no longer final

    protected Money() {}         // required by JPA — amount null

    Money(BigDecimal amount) {
        if (amount == null) {
            throw new RuntimeException("amount is required");
        }

        this.amount = amount;
    }
}

Your always-valid Money can now be built with a null amount too.

The trap isn’t contained to one class. It spreads to every value object you embed.

Notice what’s happening. You’re no longer modelling the domain — you’re shaping it to fit the ORM. You drop final, add constructors you’d never write, expose state you meant to hide — not because the business asked for it, but because the ORM expects it that way.

You end up violating the very principles the domain is supposed to protect, encapsulation first among them, just to keep the persistence framework happy.

That is not Clean Architecture.

Want to avoid the ORM trap?

📅 Join me: Clean Architecture for Backend Developers on Wed 26th Aug, 5:00 - 6:30 PM (CEST)

✅Domain ≠ ORM

Read more

Subscribe now

Every project starts simple

Most enterprise applications begin with relatively simple requirements.

Creating records.

Updating data.

Calling external systems.

Displaying results.

At this stage, almost any architecture works. The codebase is small, everyone understands it, and adding new features is straightforward.

Then the project grows.

“Just this once”

A business rule needs data that’s already available in the repository.

Instead of passing it back to the use case, the rule is implemented directly in the repository.

It’s only a few lines.

No one wants to create another object or move data around.

The feature ships.

A few weeks later, another feature needs something similar.

The repository already knows about the data, so another business rule is added there.

Still reasonable.

Still working.

Still “just this once.”

Convenience becomes the architecture

As deadlines become tighter, convenience starts winning.

A controller performs a quick permission check because it’s only needed there.

A service calls another service because it avoids duplicating code.

An external API client starts making business decisions because it already has the response.

A repository calculates values because it has all the necessary information.

None of this breaks the application.

But it weakens the boundaries between business logic and infrastructure.

The cost doesn’t appear immediately

This is why architectural decay is so difficult to notice.

The application still works.

Tests still pass.

Deployments continue.

The problem appears months later.

A business rule needs changing.

Now the team isn’t sure where that rule actually lives.

Part of it is in a controller.

Part is inside a repository.

Another piece exists in an API adapter.

There’s similar logic somewhere else too—but no one knows whether it’s safe to change.

A feature that should have taken an hour becomes an afternoon of investigation.

Not because the rule is complicated.

Because the architecture is a Big Ball of Mud.

You’re told: “Why is it taking so long? It’s just a simple requirement.”

The trap is delaying

Most teams recognize when the codebase is becoming harder to change.

They simply postpone doing anything about it.

“We’ll clean it up later.”

“We’ll refactor after this release.”

“We don’t have time right now.”

Meanwhile, every new feature adds another dependency, another shortcut, another place where business logic leaks into infrastructure.

Eventually, everyone agrees the system needs refactoring.
It’s just too difficult to start.

Join the live training session:

Clean Architecture for Backend Developers

🗓 Aug 26
⏰ 5:00–6:30 PM (CEST)

🏆Register now

Subscribe now

“How to handle errors properly?”

You’ve seen:

• SQLException and DataAccessException caught inside controllers

• catch (Exception e) returning a hand-rolled 500

• giant try/catch blocks wrapping every endpoint

• RuntimeException thrown and swallowed at random

And nobody agrees on the “right” way to do it.

Start where those mistakes happen — the API layer — and get one rule right: a controller turns errors into HTTP responses, and it should never reach for a database or framework exception to do it.

Error Handling at the API layer

This layer should turn errors into HTTP responses.

Examples:

• HTTP status codes

• error messages

• API response bodies

❌ Controllers should NOT handle database/framework errors

@GetMapping("/orders")
public ResponseEntity<?> getOrders() {

    try {
        return ResponseEntity.ok(orderRepository.findAll());
    } catch (DataAccessException e) {
        return ResponseEntity.status(500).body("Database error");
    }
}

That’s the wrong place for database exception handling.

👉 I’m running a live workshop where we walk through a working e-shop example with a pipeline architecture, so you can see how it works in practice.

No rebuild tricks. No “it passed CI but broke anyway” surprises.

Join Pipelines Workshop →

€100 off with code EARLYBIRD100 — limited spots.

✅ The API layer should turn errors into responses — via a global exception handler

Read more

Subscribe now

Logging injected directly into use cases, services and handlers is justified as:

• “we need debugging”

• “we need traceability”

• “we need observability”

But…

❌Logger in every use case

• every use case now knows about logging

• business logic is mixed with runtime reporting

• logs become part of how code is “explained”

class CreateOrderUseCase {

    private final Logger logger;

    public CreateOrderUseCase(Logger logger) {
        this.logger = logger;
    }

    public OrderResult execute(CreateOrderCommand cmd) {

        logger.info("CreateOrder started");

        Order order = new Order(cmd.userId());

        logger.info("Order created", Map.of(
            "orderId", order.getId()
        ));

        return new OrderResult(order.getId());
    }
}

⚠️Structured logging doesn’t fix the real issue

After a while, debugging becomes painful, so you switch to structured logging:

logger.info("OrderCreated", Map.of(
    "userId", cmd.userId(),
    "orderId", order.getId()
));

This is better:

• easier to search

• consistent format

• better for tools

But the real problem doesn’t change.

You still have logging calls inside every use case.

You’ve just improved how logs look.

🚀 Register now: ATDD – Acceptance Testing Workshop
Get 100 EUR off with code DISCOUNT_100

✅Infrastructure Layer: Logging outside the use case

Read more

Subscribe now

“Where should validation go?”

You’ve seen:

• validation in controllers

• validation in services

• validation duplicated in multiple places

And no one is really sure what’s “correct”.

So let’s make it concrete.

1. Validation at the API layer (input checks)

This is the first place data enters your system.

Here you check things like:

• required fields exist

• types are correct

• format is valid (email, date, UUID, etc.)

Example:

• email is missing → reject request

• age is a string → reject request

• orderDate is "not-a-date" → reject request

The API layer’s job is to fail fast with clear errors for malformed input, so the application and domain layers can work with clean, well-typed data.

2. Validation in the Application Layer (policies - use case rules)

This is where most real mistakes happen.

This layer handles rules like:

• cannot create shipment if stock is insufficient

• order cannot be placed if cart is empty

• cannot refund payment if transaction is already settled beyond refund window

• cannot process payment if currency is not supported for merchant

• cannot cancel order after it has been shipped

• cannot apply discount code if it is expired or not eligible

These are not input checks anymore.

They are policies. A policy is a rule about whether an action is allowed right now, given the current state of the world.

Every one of these needs something outside the aggregate itself to evaluate — inventory, the clock, a merchant config, a discount catalog. In DDD terms, they cross the aggregate boundary.

That’s why they don’t belong in the domain object. An Order alone doesn’t know whether stock exists. The application layer orchestrates: it fetches what’s needed, evaluates the policy, and either proceeds or rejects.

Example flow:

• API sends a valid, well-formed request

• application checks the relevant policies

• if a policy fails → reject here, before touching the domain

This is where you stop things that are technically valid, but not allowed in this situation.

⚡ Register now: ATDD – Acceptance Testing Workshop
Get 100 EUR off with code EARLYBIRD100

3. Validation in the Domain Layer (invariants)

This is the strictest level.

These are rules that must never be broken, no matter where the code is called from.

An invariant is a rule that must always hold for a given object, no matter who calls it, from where, at what time.

Examples:

• order must always have at least one line item

• order total cannot be negative

• payment cannot be “SUCCESSFUL” without a transaction reference

• reserved quantity cannot exceed available stock

• order status must follow valid transitions: CREATED → PAID → SHIPPED → DELIVERED

• order cannot have SHIPPED status without a tracking number

If this is broken, your system is already inconsistent.

So this validation:

• is enforced when creating or modifying core objects

• is tied directly to the business model itself

The key principle: the domain never trusts its callers.

Even if the API already checked something, the domain re-checks any invariant. Why? Because the domain can be invoked from anywhere — a job, an event, a test, another bounded context. It cannot assume a well-behaved API sits in front of it.

What you should NOT do

This is where most real-world code goes wrong:

Read more

Subscribe now

Developers like DTOs. And wrappers. And more wrappers.

Until your “simple” API layer turns into a tower of classes no one can read, tests become painful, and adding a new field feels like a chore.

DTOs and mappers are tools — not dogma. Clean Architecture doesn’t say “wrap everything 5 times.” It says: be intentional about what crosses boundaries.

The Problem

Many codebases follow a pattern like this:

Domain objects
   ↓
Domain DTO
   ↓
Application DTO
   ↓
API DTO
   ↓
JSON

That’s 3–4 layers of wrapping for the same data, plus mappers everywhere.

To be clear — sometimes multiple layers are justified. If you're serving both GraphQL and REST from the same domain, or maintaining a published API contract that must change independently from your domain, extra DTOs earn their keep. The problem isn't layers — it's layers that exist "just in case."

The result:

• Lots of boilerplate

• Hard to understand what actually changes the domain

• Fragile tests because every layer must be mocked

• Accidental complexity: devs can’t tell which layer matters for business rules

🚀 Register now: Acceptance Testing Workshop
Get 100 EUR off with code EARLYBIRD100

💡Code Example

Over-Wrapping Everything ❌

Read more

Subscribe now

When people try Clean Architecture… they often end up with bloated application layers and empty domain layers.

Application Layer:
   - Validate input
   - Load entities
   - Perform business logic
   - Call repositories
   - Call gateways
   - Publish events

Domain Layer:
   - Entity with getters and setters

That’s an anemic domain, not a rich domain.

The domain doesn’t actually do anything. All the rules are in the application layer.

In Clean Architecture, we’re supposed to have a rich domain, which fits in with DDD.

❌Empty Domain

If you’re used to CRUD, you probably see entities as simple data structures with public getters and setters.

class Order {
    private int id;
    private List<Item> items;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public List<Item> getItems() {
        return items;
    }

    public void setItems(List<Item> items) {
        this.items = items;
    }
}

class Item {
    private String sku;
    private int quantity;
    private boolean expired;

    public String getSku() {
        return sku;
    }

    public void setSku(String sku) {
        this.sku = sku;
    }

    public int getQuantity() {
        return quantity;
    }

    public void setQuantity(int quantity) {
        this.quantity = quantity;
    }

    public boolean isExpired() {
        return expired;
    }

    public void setExpired(boolean expired) {
        this.expired = expired;
    }
}

Looks fine… but the business rules live elsewhere (application layer).

Your application service does this:

public void addItemToOrder(Order order, Item item) {
    if (item.isExpired()) {
        throw new ExpiredException();
    }

    List<Item> items = order.getItems();
    if (items == null) {
        items = new ArrayList<>();
    }

    if (items.size() > 10) {
        throw new LimitExceededException();
    }

    items.add(item);
    order.setItems(items);
    orderRepository.save(order);
}

All the rules (expiration check, limit check) live in the application layer.

The entity is just a data container.

Basically, you’ve moved all the complexity into a layer that’s supposed to orchestrate, not decide.

❌Bloated Application Layer

Read more

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

Most “Clean Architecture” codebases still revolve around SomethingService.

• UserService

• OrderService

• PaymentService

And inside those services?

• business rules

• orchestration

• validation

• database calls

• sometimes HTTP logic too

Everything… everywhere… with multiple use cases all in one file.

Why “Services” Are a Dead End

Services usually start like this:

“We’ll put business logic in services so controllers stay thin.”

And for a while, it works.

But over time:

• Services grow without a clear responsibility

• Methods multiply

• Everything depends on everything

• Tests become slow, fragile, and heavily mocked

You don’t know what the system actually does.

Only what data it has.

What a Use Case Actually Is

A use case represents one business functionality.

Not a resource.
Not an entity.
Not a technical operation.

Examples:

• RegisterUser

• PlaceOrder

• ApproveLoan

• CancelSubscription

• GenerateInvoice

Each use case answers one question:

What does the business want to achieve in this scenario?

Services vs Use Cases

Services (group data):

• Organized around entities

• Grow horizontally

Use Cases (express behavior)

• Organized around behavior

• Stay focused

If you have a UserService, ask yourself:

What is the use case here?

Because “user” is not a behavior.

💡Code Example

Read more

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

I was trying to add a small feature to our order system.

Simple, right? Just a validation: “Orders over $10,000 require manager approval.”

Two hours later, I was deep in a mess:

• Domain entities glued to JPA annotations.

• Use cases directly calling repositories.

• Controllers scattered across three packages.

I thought: “How is anyone supposed to change this without breaking everything?”

Dependencies were everywhere, pointing the wrong way. Every small change became a massive headache.

The Daily Pain

• Changing a business rule? Better hope no one touched your domain logic with a framework dependency.

• Writing a test? Say hello to spinning up DBs, mocking everything, or manually handling try/catch just to check if something works.

• Refactoring? One wrong move and the system falls apart.

I realized: if your core logic depends on infrastructure or frameworks, everything else becomes fragile.

What Does “Depend” Mean?

You’ve got a dependency anytime you:

• Import a class

• Call a method

• Reference a concrete implementation

• Require a framework to compile

Red flags I see all the time:

• A use case importing Spring annotations ❌

• Domain entities referencing ORM ❌

• REST controllers sneaking into inner layers ❌

Use Case Depends on Infrastructure ❌

Read more

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

Data flows from external sources (like the UI) to the core logic and back out:

1. Frontend: Send request to Backend

The user enters the SKU and quantity, then clicks “Place Order.” The frontend sends this data to the backend as a REST API request.

2. Backend: Presentation Layer → Use Case

The REST API receives the JSON request, converts it into a Request DTO, and delegates the work to the Use Case. The controller stays minimal and doesn’t contain any business logic.

3. Backend: Use Case → Domain Layer

The Use Case performs basic validation of the Request DTO, and calls repositories to retrieve entities. The Use Case may create or save entities via repositories and can call methods on those entities to execute business logic.

4. Backend: Domain Layer → Use Case

The Domain Layer returns entities and computed results — such as the product details, total order price, and order status — back to the Use Case.

5. Backend: Use Case → Presentation Layer

The Use Case prepares a Response DTO with the processed results from the Domain Layer and sends it to the REST API.

6. Backend: Presentation Layer → Client

The REST API formats the response and returns it to the client (Frontend) for display.

7. Frontend: Present to user

The frontend receives the backend response and displays the order confirmation, showing details like the product, quantity, total price, and order status.

Data Flow

Data flow defines how information moves between the layers of your system — from the user interface, through the business logic, and back out again.

• Each layer has a single responsibility.

• Dependencies always point inward, toward the core logic.

• You can change external details (UI, database, frameworks) without breaking your domain rules.

Real-life Example: Ordering System

Applying Clean Architecture on the backend (for an e-commerce system).

1. Frontend: Send request to Backend

On the Frontend, user inputs the SKU and quantity, and clicks button to “Place Order“. Then Frontend calls the Backend REST API.

Let’s see what are the Clean Architecture Layers are on the Backend.

2. Backend: Presentation Layer → Use Case

On the Backend, the Presentation Layer is generally the REST API (or it might be SOAP Service, or Message Consumer, etc.).

The REST API has received the request as JSON. We have frameworks that automatically convert the JSON into a Request DTO. In the example below, the Request DTO is the PlaceOrderRequest.

We keep the REST API controller minimal. We just pass the Request DTO to the use case. In this case, we pass the PlaceOrderRequest to the PlaceOrderUseCase.

The reason is because the REST API controller should not have knowledge of application/business logic, it just delegates.

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @PostMapping
    public ResponseEntity<PlaceOrderResponse> placeOrder(@RequestBody PlaceOrderRequest request) {
        var response = placeOrderUseCase.execute(request);
        ...
    }
}

Read more