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