Let's talk

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

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

You open a PR labelled:

“API redesign — no behavior change”

Looks fine.

Merged.

The one-line acceptance test change goes unnoticed.

Six months later, a regression bug slips through.

The acceptance test that was supposed to catch it didn’t.

Why?

Because the test was quietly changed at the same time as the code.

That’s the problem.

If the behavior didn't change, the acceptance test shouldn't need to change.

The driver should handle it.

✅The test stays the same — the driver changes

Look at PlaceOrderPositiveTest.java in the shop’s system-test module:

@TestTemplate
@Channel({ChannelType.UI, ChannelType.API})
void shouldCalculateBasePriceAsProductOfUnitPriceAndQuantity() {
    scenario
            .given().product()
                .withUnitPrice(20.00)
            .when().placeOrder()
                .withQuantity(5)
            .then().shouldSucceed()
            .and().order()
                .hasBasePrice(100.00);
}

This test has no idea whether the order is placed by POST /api/orders or POST /api/purchases.

It has no idea whether the UI’s place-order button is selected by [aria-label="Place Order"] or by some new CSS class.

It also has no idea whether the ERP returns the product’s price as price or unitPrice.

Read more

Let's talk

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

“AI can write the tests.”

Finally.

All those tests nobody has time to write.

No more days spent waiting for manual QA before every release.

Six months later…

More code.

More PRS.

But releases aren’t faster.

QA is still testing everything manually before anything ships — exactly as they were last year.

And the bugs? Still there.

Now management wants to know:

What did we actually get for the money?

You have plenty of numbers to show them.

More code.
More PRs.
More tests.

But none of those numbers answer the question.

Because more code isn't the same as safer releases.

AI copies whatever it finds

Ask AI to write a test.

But what if your e2e suite is full of tests coupled to the UI?

Click the button.
Fill the field.
Check the screen.

AI just writes hundreds more tests like that.

Faster.

It doesn't stop and ask:

“Is this a good way to test this application?”

It looks at the tests you already have and learns:

“This is how tests are written here.”

You had a speed limit

Before AI, writing tests was slow.

That was annoying.

But it also limited how many bad tests you could create.

Your team could only write so many brittle E2E tests before the sprint ended.

AI removed that limit.

Now you can write hundreds in the time it used to take to write a few.

But the tests aren’t any better.

They’re still coupled to the UI.

Still break when the UI changes.

Still create more work for the team.

Before AI writes 100 more tests

AI writing tests isn’t the problem.

AI writing bad tests faster is.

The problem is giving it a bad test suite to learn from.

❌ If your tests are all coupled to the UI, AI will keep generating tests like:

click("Place Order")

✅ Instead, fix the test, so that it's coupled to the domain rather than the UI:

shop.placeOrder()

Now AI can do what it’s good at:

Write hundreds more. Fast.

⚡Join our next live courses

• ATDD: Stop Shipping Bugs

• Clean Architecture: In Practice

• Pipelines: Stop Release Nightmares

Ealy bird: €100 off with code EARLYBIRD100

ATDD in Legacy Code: catch regression bugs before production — in banking, insurance, and healthcare systems.
Hands-on work with your teams. Limited spaces for 2027.

Let's talk

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 the free edition of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

Someone can spend 20 years getting better at software engineering.

Or they can spend 20 years repeating the same mistakes.

The “I’ve Been Doing This for 20 Years” Developer

There’s a particular kind of senior engineer who is difficult to work with.

They’ve been doing this for a long time.
They’ve seen everything.
They have an answer for everything.

And every new problem gets solved with something they’ve already done before.

You suggest a different approach.
They tell you why it won’t work.

You show them an example.
They explain why that example is different.

You point out a problem with their approach.
They tell you they’ve been doing this for 20 years.

And that’s supposed to end the discussion.

Experience Doesn’t Fix Bad Habits

It makes them harder to see.

A developer who has spent 10 years writing huge classes doesn’t necessarily become better at design.

They might simply become extremely fast at writing huge classes.

A developer who has spent 10 years avoiding tests doesn’t become good at testing.

They become very experienced at working without tests.

And someone who has spent years solving every problem with another layer, abstraction, framework, or design pattern can become incredibly experienced at overengineering.

Experience makes you better at whatever you repeatedly practice.

Including the wrong things.

Stop Counting Years

Years of experience are a terrible measurement of engineering ability.

A developer with three years of experience who constantly learns, experiments, gets feedback, and improves their approach can be far more effective than someone with fifteen years who stopped learning five years ago.

I’ve seen developers with relatively little experience who can walk into an unfamiliar codebase and start asking the right questions.

And I’ve seen extremely experienced developers who can’t change their approach even when it’s clearly not working.

Good Engineers Say “I Was Wrong”

The best engineers can look at their own code and say:

“I wouldn’t write this that way today.”

Years of experience can tell you how long someone has been in the game.

It doesn’t tell you how well they’ve played it.

Getting better means being willing to rethink how you’ve been doing things.

Join the live session:

Clean Architecture for Backend Developers

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

🏆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

The first time you see Hexagonal Architecture, it can feel like a lot.

Schedule a shipment.

You're used to something like: ShipmentHttpController, talking straight to the ORM and the FedEx API. One class, two integrations.

Then you look at the Hexagonal Architecture version of the same feature:

• driving adapter (ShipmentHttpController)

• driving port (ScheduleShipmentUseCase)

• the hexagon itself (Shipment, Address, PackageDetails, ShipmentRepository, CourierGateway)

• driven adapters (SqlShipmentRepository, FedExCourierGateway).

And here’s where things can get out of hand.

You start creating all of these classes before you actually need them.

The Starting Point

🚫 Problem: No pain yet

One feature, one caller, one integration on each side.

✅ Solution: Ship it as a single class

There’s nothing to abstract until something actually hurts.

One class handles the HTTP request, runs the validation, talks to Postgres through JPA, and calls the FedEx SDK directly. No ports, no adapters, no domain model.

This isn't the design we'd want to keep forever: it’s slow to test and it’s going to get worse as more logic lands in it — but it hasn’t gotten worse yet.

Step 1 — Driven Ports Keep I/O Out of the Way

🚫 Problem: Tests are slow

Every test hits a real Postgres instance and the real FedEx test instance, so they’re slow, and the test instance goes down more often than the code changes.

✅ Solution: Use driven ports for I/O

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. This article is part of the TDD in Legacy Code series.

Subscribe now

Component Tests are fast because they stub their dependencies

Component Tests give us fast feedback by testing a component in isolation.

The Frontend Team stubs out the Backend in Frontend Component Tests in Legacy Code; the Backend Team stubs out the External System (the ERP) in Backend Component Tests in Legacy Code.

But your stubs might be wrong!

When the Frontend stubs the Backend, it makes an assumption: “POST /api/orders returns 201 with { orderNumber }.”

But what if the Backend Team renames that field, or changes the status code, or moves the endpoint. What happens to the Frontend’s Component Tests?

They stay green. They’re still testing against the stub which hadn’t changed — but the stub’s assumption is now wrong.

The bug doesn’t show up until the Frontend and the Backend actually run together — when the Acceptance Test fails.

How to catch stub mismatch? Contract Tests

The Frontend says:

“This is what I expect from the Backend.”

Pact turns that expectation into a contract.

The Backend then runs the contract against itself.

If the Backend no longer matches what the Frontend expects, the Backend build fails.

You don’t write a new test from scratch. You take a Frontend Component Test you already have, and replace the stub with a contract.

Here are the steps to introduce Contract Tests in Legacy Code. You’ll get tasks to implement in your GitHub Sandbox Project. ⬇️⬇️⬇️

Read more

Subscribe now

“Architects don’t code.”

I’ve heard this sentence too many times.

And every time, I worry.

Because the moment someone thinks coding is beneath them, they are already moving away from the thing they’re supposed to understand.

The code.

The good ones

The best architects I’ve worked with never stopped writing code.

They reviewed pull requests.

They paired with developers when something got stuck.

They built the first few features of what they designed.

They understood the pain developers faced because they experienced it themselves.

"Coding is below me"

In many companies, an “architect” is what you get when there is nowhere else to go except management.

The architect stops coding. Not because the job doesn’t need it, but because the title says they’ve outgrown it.

Then the calendar fills up. Meetings, roadmaps, steering committees.

A year later they are deciding how the system should be built, without knowing how it is built.

“But nobody writes code by hand anymore”

This is where someone brings up AI.

If developers are generating most of the code, why should an architect write any?

Because typing the code was never the point. Knowing how the system is actually built was.

You can know that without writing every line yourself. You can’t know it without reading any of it.

Someone still has to notice that logging is now done three different ways in three different places. Or validation. Or error handling. Nobody told the model how this codebase does any of it, so it picked something reasonable each time.

What you want is consistency in the design itself: the same kind of problem solved with the same structure everywhere, so that a developer who has read one part of the codebase can predict what the next part looks like. No diagram gives you that. It comes from someone reading the code and saying, we already have a way of doing this, use that one.

That work is closer to the code than a diagram ever gets you. An architect who only reviews the design, and never looks at what came out the other end, is exactly as far away as before. The tooling is just newer.

If anything, AI makes it worse. More code arrives, faster, and less of it has been thought about by anyone. Judging whether it fits the system is more work than it used to be, not less.

Don’t become an ivory tower architect

The dangerous architect is the one who designs a system they would never have to maintain.

There is no way to find out what a design costs except to build something in it. Add a feature. Change one that already exists. Fix a bug in it six months later. That’s when you find out which parts of your own design fight you — the layer you have to touch every time, the abstraction nobody can extend without asking you first, the test that takes ten lines of setup before it can assert anything.

And don’t expect anyone to report it back to you.

Developers mostly won’t tell you the design is painful. You’re the architect, you decided it, and to them it’s a given — something to work around, not something to question. The more junior they are, the less likely you are to hear about it at all. What comes back is “it took a bit longer than we thought.”

If you haven’t opened the codebase in months, you’re not designing the system anymore.

You’re describing one.

Join the live training session:

Clean Architecture for Backend Developers

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

🏆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

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

Subscribe now

When I started my career in software development, I thought I was surrounded by the wrong people.

Nobody wanted to write tests.

Nobody cared about clean code.

Every conversation about improving the codebase turned into an argument.

I remember thinking:

“If I just join a better company, things will be different.”

The next company was supposed to be different

I moved to another company.

Surely this time it would be different.

More experienced developers.

Better engineers.

Except...

The same problems were there.

“Tests are a waste of time.”

“We’ll clean up the code later.”

“We have always done it this way.”

Being a Senior Developer didn’t change anything

As a Senior Developer, I though:

“Now I can finally influence how we build software.”

We would write better code.

We would add tests.

We would stop rushing changes into production.

I was wrong.

Even getting people to write one test was a battle.

“Why would we write twice as much code?”

“Now we have to maintain the application code and all the tests too?”

The smaller company as a Tech Lead

The next move was to a smaller company, as a Team Lead.

This time I did things differently.

I stopped waiting for permission. In my own time, over several months, I built a Clean Architecture template — layered, testable, with unit tests already in place.

When I recruited developers for the team, I stopped screening only for years of experience. I screened for whether they cared about quality.

Then I built the first module with the template myself, end to end, so there was something real to point at.

And then I trained the team to do it the same way.

Six months later

Within six months, that team had shipped more features than the “senior” developers at my previous companies had managed in years.

Same industry. Same kind of problems.

The difference wasn’t that these developers were smarter. It was that nobody had to be convinced. The template made the right way the easy way, the hiring made the standard shared, and the training made it something the whole team could do — not something one person kept arguing for.

That’s what I had been getting wrong for years.

You don’t change a team by caring harder than everyone else. You change it by building the thing, showing it works, and bringing people with you.

The template was what made that possible. So that’s what I want to show you how to design.

Join the live training session:

Clean Architecture for Backend Developers

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

🏆Register now

🏆 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

Subscribe now

“Clean Architecture is overkill.”

I’ve heard that a lot of times.

Too many interfaces. Too much abstraction. Too much indirection.

And some people go further and argue it makes the system harder to maintain, harder to understand.

The overhead is real

Compared to a plain CRUD application, yes, there are more interfaces. Specifically for anything that is infrastructure: databases, the file system, external REST APIs.

Instead of directly opening an HTTP client connection, or directly opening a database connection, or directly working with the ORM, you put an interface in between. Your use cases depend on those interfaces, i.e. abstractions of infrastructure, rather than directly depending on the infrastructure details.

And as a developer you have more files to look at, because when you open your use case class you’re not going to see the direct call to the HTTP client.

That’s overhead. I’m not going to pretend it isn’t.

But it’s nothing compared to the size of the codebase

For midsize and larger projects, that overhead is nothing compared to the size of the codebase.

It’s like someone arguing: let’s not use Java/C#, let’s use C/C++ for everything, because C and C++ are faster. Microseconds, milliseconds, whatever the number is.

And yet developers still use Java and .NET anyway, because the trade-off is worth what they get back.

Same thing here.

A handful of extra interface files is not the argument they think it is.

The harder one: domain entities vs ORM entities

The complaint that’s genuinely harder to argue against is this one: you have your domain entities and you have your ORM entities, so now you’re doing double the work and maintaining double the code.

Initially, on a really small project, I can see that argument being hard to fight. At that point the domain entities and the ORM entities are most likely one-to-one identical. So yes, it does feel like duplication. It looks like you typed the same class twice for no reason.

But what happens, quite often, is that enterprise projects grow in complexity. And that’s exactly when being coupled to the database hurts you.

The one-to-one mapping stops being one-to-one, and the class they were calling duplication turns out to be the reason you can change the business logic without being trapped by your database structure.

Stop counting lines of code

Instead of asking: “How many extra files does Clean Architecture create?” or “How many extra lines of code does this add?”…

Think about how hard it is to understand the code.

Separation of concerns means separating business logic from infrastructure so that it’s easier for our brains.

When you’re thinking about business requirements, you don’t want to also be thinking about what the external REST API DTO looks like. Later when you shift to integrating with external systems, that’s when you think about the nitty-gritty of the I/O and the DTOs. Those are two separate concerns. You go into one of them at a time.

That’s less effort to understand the code. That’s the payoff, and it doesn’t show up anywhere in a line count.

So next time someone tells you Clean Architecture is overhead, don’t argue about the number of files. Ask them how many things they have to hold in their head to change one business rule.

⚡Clean Architecture in practice

How do you separate business logic from infrastructure?
How to decouple the domain from the ORM?
When is an abstraction useful—and when is it over-engineering?

Join the live training session:

🗓 Clean Architecture for Backend Developers (Wed Aug 26)

🏆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

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

Most developers think architecture is someone else’s job.

It’s what the architects do.

Or the tech leads.

Or the people who spend their days drawing boxes and arrows.

It’s not on your job description, so it’s not your problem.

Except it is.

By the time you’ve been building software for a few years, you’re already making architectural decisions.

You just don’t call them that.

A year later it's called "The Architecture"

You’re implementing a new feature. An order has to notify the warehouse once it’s paid.

You need to decide where that notification comes from.

Do you call the warehouse API straight from the payment handler, because it’s two lines and the ticket is due Thursday?

Do you publish an event instead, and let the warehouse subscribe to it?

Do you put the rule — an order notifies the warehouse once it’s paid — inside Order, or in whichever service happens to be holding it?

Do you reuse the HTTP client that’s already wired up in the payment module, or give the warehouse call its own?

None of these decisions feel like “architecture.”

They seem to be just implementation details.

Until a year later.

A year later, a new developer joins and asks why payment knows about the warehouse. Why the notification rule lives in a service instead of in the order. Why there are four HTTP clients configured against the same host.

Nobody has an answer. The person who made those calls has moved on, or doesn’t remember, or never thought about it much...

But the answers have hardened. The direct call became the pattern everyone copied. The rule in the service became the reason Order can’t be tested without a database. The four clients became the reason a timeout change takes a day.

That’s what the team now calls “the architecture.”

Nobody designed it. It accumulated.

The line between developer and architect isn't a promotion

Architecture isn’t something you do before writing code.

It’s something you do every time you write code.

So the difference between a developer and an architect isn’t the title, and it isn’t permission from someone above you. It’s whether the decision got made on purpose.

Sometimes the direct call really is the right answer.

Picture two developers who both write it. The first one weighed it: the warehouse call is rare, a failed notification is recoverable, an event bus would cost more than it saves right now. The second one wrote it because it was the shortest path on a Thursday.

Read the code today and you can’t tell them apart. It’s the same two lines.

The difference shows up the day the assumption breaks — when the call stops being rare, or a lost notification starts costing real money.

The first developer knows exactly what they traded away, so they recognize the moment the trade stops paying.

The second left nothing behind to revisit, so nobody notices. The line just gets copied into the next three features, because by then it looks like a decision somebody made.

Next time you reach for the shortest path, ask the architect’s question: what does this make cheap later, and what does it make expensive?

You’re already making the decision.

Make it deliberately.

⚡Clean Architecture in practice

Which class should own a business rule?
What’s allowed to depend on what?
Which calls to the outside world you should be able to swap for a fake when you test?

Nobody tells you that along with the title.

Join the live training session:

🗓 Clean Architecture for Backend Developers (Wed Aug 26)

🏆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

One of the biggest mistakes I see in Spring applications is developers mocking JPA.

When tests become slow, they replace the database with mocked JpaRepository interfaces.

The tests are faster.

But the architecture is now coupled to the ORM.

Why Mocking JPA Is a Design Smell

Developers mock JPA because they want:

• fast tests

• no database

• isolated business logic

Those are good goals.

Mocking JPA isn’t.

Why?

• You’re mocking a framework you don’t own

• Your tests depend on Spring Data instead of your own abstractions

• Changing persistence forces you to change unit tests

• Business logic stays coupled to the ORM

The mock removes the database.

It doesn’t remove the dependency on the ORM.

The Real Problem

One team I worked with couldn’t upgrade their ORM for months because of a change to how inheritance was mapped.

The application wasn’t the problem.

The business logic wasn’t the problem.

The problem was that the ORM had leaked into the application layer and the tests.

A change in persistence rippled through the entire codebase.

A concrete example:

• In .NET, EF Core's Table-Per-Hierarchy inheritance auto-adds a Discriminator column, and its behavior has shifted across major versions — nullability, length, how it's configured and queried.

• An upgrade changes the discriminator, and that change ripples into every piece of code that touches those entities.

• JPA has the same trap: single-table inheritance auto-creates a DTYPE discriminator column, so a change to the mapping reaches straight into the application layer and its tests.

💡 Code Example

Read more

Subscribe now

Manager:

"We're behind schedule! We need more developers."

Senior developers don’t think:

"Great, we'll finish sooner."

Instead, it's more like:

“We’re about to spend the next month onboarding.”

Because they know what comes next…

• Onboarding

• Interruptions

• Explaining codebase

• More meetings

• More PR reviews

• More merge conflicts

The Rules Nobody Wrote Down

The system is a tangled mess of dependencies.

But after working on it for years, experienced developers have learned to navigate the mess.

They know:

• “Don’t touch that class.”

• “Only Mike understands billing.”

• “Changing this always breaks reporting.”

• “That test is flaky, just rerun it.”

They’ve built a mental map of the codebase.

A new developer hasn’t.

Every feature starts with: “Who knows this part of the system?”

They need someone to explain the codebase, the architecture, and all the hidden pitfalls nobody documented.

More detailed code reviews.

More meetings.

More Developers. Less Progress.

The bottleneck isn’t the number of developers.

It’s the architecture.

When the system is tightly coupled, every change collides with another change.

Adding more people doesn't remove the bottleneck.

It just makes it worse.

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

Clean Architecture in Practice →

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

🏆 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. This article is part of the TDD in Legacy Code series.

Subscribe now

Backend Component Tests provide fast feedback

We’ve seen in the previous article Backend Component Tests in Legacy Code, that Component Tests can provide us with fast feedback. The Backend Team can test the Backend in isolation, by stubbing out External Systems (such as the ERP).

But they can be a maintenance nightmare!

In Backend Component Tests in Legacy Code, we illustrated the “simplest” Backend Component Test.

The simplest way to write a Backend Component Test is to stub the External System inline (with WireMock), call the Backend API directly (with WebTestClient), and read the response by digging into raw JSON paths.

@Test
void shouldCreateOrderWithTotalPrice() {
    // Arrange
    var productDto = new ProductDto(2.50);
    var productDtoJson = objectMapper.writeValueAsString(productDto);
    erpWireMockStub.stubFor(WireMock.get(“/products?sku=APPLE1001”)
        .willReturn(WireMock.aResponse()
            .withStatus(200)
            .withHeader(“Content-Type”, “application/json”)
            .withBody(productDtoJson)));

    var orderRequest = new OrderRequest(“APPLE1001”, 5);

    // Act & Assert
    webTestClient.post()
        .uri(“/api/orders”)
        .contentType(MediaType.APPLICATION_JSON)
        .bodyValue(orderRequest)
        .exchange()
        .expectStatus().isCreated()
        .expectBody()
        .jsonPath(“$.totalPrice”).isEqualTo(12.5);
}

The problem is that this test is coupled in three places at once: the ERP wire format (the WireMock stub), the Backend API endpoint (webTestClient.post().uri("/api/orders")), and the response (the raw $.totalPrice JSON path).

If the API endpoint changes, or the ERP’s wire format changes (a renamed field, a different status code), then many such tests may break, so we have to waste time fixing tests. The plumbing is also copy-pasted into every test.

How to write maintainable Backend Component Tests?

In this article, I’ll show you how to introduce layers of abstraction, i.e. Component Test Architecture, so that you spend much less time writing & maintaining these tests.

Here are the steps to introduce Maintainable Backend Component Tests in Legacy Code. You’ll get tasks to implement in your GitHub Sandbox Project. ⬇️⬇️⬇️

Read more

Subscribe now

Think back to why you got into this.

Not the title or the pay bump. You wanted to be the person who shapes how the system is built instead of just closing the next ticket.

But how much of last month did you actually spend being that person? Or did it disappear into a three-day slog to make a small change — hoping it wouldn’t break something you couldn’t see?

“Can you just add a field?”

You know the one. A stakeholder wants one extra value on a form, and it lands on your desk — because you’re the one who gets handed the changes nobody else wants to touch. It’s a field. An afternoon, you figure.

Three days later you’re still in it.

The field touched a model. The model was wired straight into a service. The service was called from four places, two of which you didn’t know existed. There were no tests, so every change was a guess you couldn’t verify. And half of it was written by someone who left eighteen months ago, in a style you spent most of Tuesday just reading before you dared touch it.

The field took twenty minutes.

Everything around it took three days.

But… it didn’t feel like work. It felt like waste. Three days of picking through someone else’s tangle just to safely add a field — and not one minute of it went into anything that mattered, or anything that even held your interest.

You closed the ticket bored, drained, and quietly resentful that this is what your week had become.

Little fixes get in the way of better architecture

What makes it maddening is that you can see the work you’d rather be doing. You want to step back and redesign this — draw the boundaries that should’ve been there, untangle the core, build something that doesn’t fight you on every change. That’s the work that’s interesting. That’s the work that makes an impact.

But you never get to it, because there’s always one more little fix in the way, and the little fixes never stop.

And here’s what all that lost time costs you — the system you actually want to build:

• The clean, decoupled layers you know how to design — where a change lands in one place instead of rippling through five — stay tangled, because you only ever get time to patch, never to reshape.

• The codebase that could be a pleasure to move through stays a maze you have to re-learn every time you open it.

• The architecture you can already picture loses, every single sprint, to one more little fix you can’t say no to.

You just notice, a year in, that you’re working as hard as ever, more bored than you’ve ever been, and no closer to the system you wanted to build.

You’re stuck in a vicious cycle

This isn’t bad luck, and it isn’t a talent problem.

The architecture is tightly coupled, so every change is slow and risky. Because every change is slow, there’s never a clear stretch of time to stop and fix the coupling — so you patch around it instead. And every patch wires one more thing to one more thing, which makes the next change even slower.

Tightly coupled architecture. When everything reaches into everything else, a “small” change doesn’t stay small — it ripples across half the codebase, because half the codebase depends on the thing you touched.

No tests, or tests you can’t trust. Without them, every change is a leap in the dark. You can’t move boldly, so you move carefully — and careful is slow.

Unreadable code. Before you can change anything, you have to understand it. If understanding takes a day, every change loses a day to just figuring out what’s there before the real work even starts.

That’s why it doesn’t just stay annoying — it compounds. And the worst part is that you can see it happening: you’re being asked to add another floor to a house you know has no foundations. Every feature makes the structure taller and shakier, and you can feel that one ordinary change, on one ordinary day, is going to bring a piece of it down.

Get the architecture right and everything else gets easier

Here’s the reframe that changes how you spend your week: the architecture isn’t a chore for when there’s spare time, and it isn’t polish you bolt on at the end — it’s the one thing that everything else rides on.

The shape of the system — where the boundaries sit, what depends on what, how independent the core is — decides whether the next change lands in an afternoon or turns into another three-day dig.

And this is exactly where a senior developer makes their mark.

You’re the one teammates already ask “where should this go?” You’re the one who can introduce a boundary, decouple the layers so the core stops depending on the framework around it — and set the pattern the rest of the codebase follows.

You know the architecture is painful

You didn’t become a senior developer to spend three days adding a field.

But that’s what a lot of backend work becomes.

Not because the feature is hard.
Because the system is.

Join the live session:

Clean Architecture for Backend Developers

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

🏆Register now

And if you want to talk it through for your situation — not the textbook version — come join the Optivem Circle Membership