DEV Community: Rômulo Pereira

Why Clean Architecture Confuses Everyone (And How I Learned to Stop Worrying)

Rômulo Pereira — Wed, 04 Feb 2026 14:03:48 +0000

I've been writing software for over 10 years now. I've seen codebases that started clean and became unmaintainable. I've inherited legacy systems that somehow still worked despite violating every principle in the book. And I've watched teams argue for hours about folder structures while missing the entire point of clean architecture.

Let me tell you something: the confusion is real, and it's not your fault.

The Framework Problem

When you start a Spring Boot project, the framework practically begs you to do this:

@Entity
@Table(name = "orders")
public class Order {
    @Id
    @GeneratedValue
    private Long id;

    @Column(nullable = false)
    private String customerEmail;

    @OneToMany(mappedBy = "order")
    private List<OrderItem> items;
}

@Service
public class OrderService {
    @Autowired
    private OrderRepository repository;

    public Order save(Order order) {
        return repository.save(order);
    }
}

This works. It's fast to write. Your DevOps team is happy because you delivered quickly. But here's the problem: your business logic now knows about JPA, Jackson, and probably a dozen other framework concerns.

Clean architecture says your domain shouldn't know about these things. But Spring Boot is right there, making it so easy to just add one more annotation.

The Package-by-Layer Trap

Most tutorials teach you this structure:

src/main/java/
  ├── controller/
  ├── service/
  ├── repository/
  └── model/

It feels natural. It's what everyone does. But it completely misses the point of clean architecture.

The problem isn't the folders—it's that this structure encourages you to think in terms of technical layers instead of business capabilities.

When you organize by feature instead:

src/main/java/
  ├── order/
  │   ├── domain/
  │   ├── application/
  │   └── infrastructure/
  ├── product/
  └── customer/

Something interesting happens: you start thinking about what the system does rather than what technologies it uses.

What I Learned Building Real Systems

In previous roles, I've worked on high-throughput billing systems and real-time data platforms. I've also architected multi-tenant public administration systems. Here's what actually mattered:

1. Business Logic Should Be Boring

Your core business rules shouldn't care about:

How data is stored (PostgreSQL? MongoDB? Firestore?)
How requests arrive (REST? GraphQL? Message queue?)
Which framework you're using

When I needed to migrate a system from MongoDB to PostgreSQL, the pain level told me everything about the architecture quality. If your business logic is tangled with database annotations, that migration becomes a nightmare.

2. Interfaces Without Purpose Are Noise

Don't create interfaces just because someone said "clean architecture needs ports and adapters." Create them when you actually need to swap implementations or isolate dependencies.

I've seen codebases with repository interfaces that have exactly one implementation, forever. That's not architecture—that's ceremony.

3. The Real Test Is Change

Can you:

Switch from PostgreSQL to another database without touching business logic?
Change your REST API to use GraphQL without rewriting services?
Replace Spring Boot with Micronaut (hypothetically)?

If the answer is "yes," you probably have decent architecture. If the answer is "are you insane?", then the folder structure doesn't matter—you're coupled.

The Practical Middle Ground

Here's what I actually do in production systems:

Keep business rules clean:

public class CancelOrderUseCase {
    private final OrderRepository orderRepository;
    private final PaymentGateway paymentGateway;

    public void execute(Long orderId, String reason) {
        Order order = orderRepository.findById(orderId)
            .orElseThrow(() -> new OrderNotFound(orderId));

        if (order.isAlreadyShipped()) {
            throw new CannotCancelShippedOrder(orderId);
        }

        if (order.isPaid()) {
            paymentGateway.refund(order.getPaymentId());
        }

        order.cancel(reason);
        orderRepository.save(order);
    }
}

Notice: no @Service, no @Transactional, no JPA annotations. Just business logic.

Adapt at the boundaries:

@Service
@Transactional
public class OrderService {
    private final CancelOrderUseCase useCase;

    public void cancelOrder(Long orderId, String reason) {
        useCase.execute(orderId, reason);
    }
}

Now the Spring stuff lives at the edge. The business logic doesn't know about it.

Stop Overthinking, Start Measuring

Instead of debating folder structures, ask yourself:

How hard is it to test my business logic? If you need to spin up a database or mock 15 dependencies, something's wrong.
How often do framework updates break my code? When Spring Boot 4.0 dropped, how many files did you have to touch?
Can a new developer understand what the system does? If they have to read through controller → service → repository → entity just to understand one feature, your architecture is hiding the business logic.

What Actually Matters

After building systems across different industries—from financial services to public administration and beyond—here's my honest take:

Clean architecture isn't about folders. It's about keeping your business logic independent from the frameworks and tools that deliver it.

You don't need perfect hexagonal architecture on day one. You need to make sure that when requirements change (and they will), you can adapt without rewriting everything.

The confusion exists because we focus on the wrong things. We argue about package names while our domain models are covered in @Entity annotations. We create elaborate folder structures while our business logic lives inside Spring controllers.

Start simple. Keep your business rules clean. Test them without mocking the world. Everything else is just details.

💻 Code Review: Focus on What Really Matters

Rômulo Pereira — Thu, 27 Feb 2025 06:31:33 +0000

Inspired by Thiago Caserta's LinkedIn post, which highlights the true focus of a code review: preventing production failures rather than obsessing over style.

Code reviews are essential to software development, but too often, they focus on the wrong things. While discussing spacing issues, variable names, and style guides can improve readability, they don’t prevent production failures. The most important question to ask during a review is:

“Will this code break in production?”

What Everyone Focuses On

Typical code reviews often revolve around:

Incorrect spacing
Variable naming preferences
Following design patterns
Code style enforcement

While these are useful for consistency, they do not prevent real-world issues. A perfectly formatted codebase means nothing if it crashes in production.

Automating Style Guide Enforcement

Rather than spending valuable code review time nitpicking style issues, teams should rely on automated tools to enforce coding standards. This allows developers to focus on what really matters: preventing production failures.

Popular Tools for Style Enforcement

Java: Checkstyle, SpotBugs
Node.js: ESLint, Prettier
Git Hooks: Husky for pre-commit checks
CI/CD Pipelines: Integrate linters into GitHub Actions, GitLab CI, or Jenkins

Examples of Automated Style Checks

Java - Enforcing Code Formatting with Checkstyle

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.1.2</version>
    <executions>
        <execution>
            <phase>validate</phase>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Node.js - Enforcing Code Formatting with ESLint & Prettier

{
  "scripts": {
    "lint": "eslint .",
    "format": "prettier --write ."
  }
}

By automating these checks, teams ensure a consistent code style without wasting time during reviews.

What Really Matters: Avoiding Production Failures

Instead of nitpicking minor details, focus on critical areas that impact system stability, performance, and reliability. A solid code review should prioritize:

Edge Cases – Will this code handle unexpected situations?

Edge cases are situations that developers might not expect during normal execution but can cause system failures. These include null values, timeouts, errors that bubble up unexpectedly, and system recovery after failures. Addressing edge cases improves software resilience and reliability.

Are there proper null checks?

❌ Bad Example (Java - NullPointerException risk):

public String getUserEmail(User user) {
    return user.getEmail(); // Crashes if user is null
}

✅ Good Example:

public String getUserEmail(User user) {
    return Optional.ofNullable(user)
                   .map(User::getEmail)
                   .orElse("No email available");
}

❌ Bad Example (Node.js - TypeError risk):

function getUserEmail(user) {
    return user.email; // Crashes if user is undefined
}

✅ Good Example:

function getUserEmail(user) {
    return user?.email || "No email available";
}

Is there a timeout handling mechanism?

❌ Bad Example (No timeout - request hangs forever):

HttpClient client = HttpClient.newBuilder().build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

✅ Good Example:

HttpClient client = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(5))
    .build();

❌ Bad Example (Node.js - No timeout set):

axios.get(url).then(response => console.log(response.data));

✅ Good Example:

axios.get(url, { timeout: 5000 })
    .catch(err => console.error("Request timed out", err));

Performance – Will this code cause performance bottlenecks?

Performance issues can lead to slow applications, high server costs, and poor user experience. Identifying bottlenecks early in code reviews helps maintain scalable systems.

Common Performance Issues:

N+1 Query Problems: Excessive database queries can slow down requests significantly.
Memory Leaks: Unreleased resources cause long-term performance degradation.
Cache Invalidation: Poor cache handling can serve stale data or overwhelm the database.
Resource Locking: Concurrent operations can cause race conditions or deadlocks.

Are there any N+1 query issues that could degrade database performance?

❌ Bad Example (Java - N+1 Query Issue in JPA):

List<User> users = entityManager.createQuery("SELECT u FROM User u", User.class).getResultList();
for (User user : users) {
    user.getOrders().size(); // Triggers additional queries
}

✅ Good Example:

@Query("SELECT u FROM User u JOIN FETCH u.orders WHERE u.id = :id")
User findUserWithOrders(@Param("id") Long id);

❌ Bad Example (Node.js - N+1 Query Issue in Sequelize):

const users = await User.findAll();
for (const user of users) {
    const orders = await Order.findAll({ where: { userId: user.id } });
}

✅ Good Example:

const users = await User.findAll({ include: [Order] });

The Reality: Style Guides Don’t Break Production—Edge Cases Do

A well-formatted codebase is nice, but a system that crashes due to unhandled exceptions, poor performance, or missing monitoring is a nightmare. When reviewing code, shift your mindset from aesthetics to stability, performance, and resilience.

Next time you're in a code review, ask yourself: Am I fixing a style issue, or preventing a production failure?

What do you focus on in code reviews? Let’s discuss in the comments!

📡 Logging Architecture: Collecting Backend Logs Effectively with AMQP

Rômulo Pereira — Thu, 06 Feb 2025 10:28:57 +0000

Log collection is essential for monitoring, debugging, and analyzing application behavior in modern distributed systems. Traditional logging methods that rely on HTTP-based log shipping can introduce overhead, tight coupling, and reliability issues.

A more efficient approach is to use AMQP (e.g., RabbitMQ) to collect logs asynchronously, ensuring scalability, fault tolerance, and real-time processing.

This article demonstrates how to implement a centralized logging system using AMQP in Spring Boot (Java) and NestJS (TypeScript) while also enabling log retrieval via a query service.

🚀 Why Use AMQP for Log Collection?
Traditional HTTP-based logging suffers from:

❌ High overhead: Frequent HTTP requests increase system load.
❌ Potential data loss: If the log collector service is down, logs may be lost.
❌ Tight coupling: Backend services need direct integration with the log storage system.

✅ Advantages of AMQP (RabbitMQ) for Logging:
✔ Asynchronous & Decoupled → Logs are sent to a queue instead of an HTTP endpoint.
✔ Reliable → If the log processor is down, messages remain in the queue until processed.
✔ Scalable → Multiple log processors can consume messages in parallel for high throughput.

🏗 Architecture Overview
Below is the high-level architecture of the logging system:

🔍 How It Works
1️⃣ Backend Services (Spring Boot, NestJS, and other microservices) send log messages to RabbitMQ asynchronously.
2️⃣ RabbitMQ (AMQP Message Queue) temporarily holds the logs, ensuring reliable message delivery.
3️⃣ A Log Processor Service consumes log messages and stores them in PostgreSQL or MongoDB.
4️⃣ A Log Query Service (Log API) allows users or external dashboards to retrieve logs for analysis.
5️⃣ Users can access logs via a dashboard, API, or external monitoring tools like Kibana or Grafana.

🏗 Implementing AMQP-based Logging in Spring Boot

1️⃣ Add RabbitMQ Dependencies:
Add the following RabbitMQ dependency to your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-amqp</artifactId>
</dependency>

2️⃣ Configure RabbitMQ:
Add the following RabbitMQ configuration in application.yml:

spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: guest
    password: guest
    virtual-host: /

3️⃣ Implement a Log Producer (Send Logs to RabbitMQ)
Create a service to send logs to RabbitMQ:

import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.stereotype.Service;

@Service
public class LogProducer {
    private final RabbitTemplate rabbitTemplate;
    private static final String EXCHANGE_NAME = "log-exchange";
    private static final String ROUTING_KEY = "log.info";

    public LogProducer(RabbitTemplate rabbitTemplate) {
        this.rabbitTemplate = rabbitTemplate;
    }

    public void sendLog(String logMessage) {
        rabbitTemplate.convertAndSend(EXCHANGE_NAME, ROUTING_KEY, logMessage);
    }
}

Now, you can send logs like this:

logProducer.sendLog("User logged in: user@example.com");

4️⃣ Implement a Log Consumer (Process Logs from RabbitMQ)
Create a listener to process log messages:

import org.springframework.amqp.rabbit.annotation.RabbitListener;
import org.springframework.stereotype.Service;

@Service
public class LogConsumer {

    @RabbitListener(queues = "log-queue")
    public void receiveLog(String logMessage) {
        System.out.println("Received log: " + logMessage);
        // Store in a database
    }
}

🏗 Implementing AMQP-based Logging in NestJS

1️⃣ Install RabbitMQ Dependencies:

npm install @nestjs/microservices amqplib

2️⃣ Configure RabbitMQ in NestJS
Modify main.ts to enable AMQP transport:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { MicroserviceOptions, Transport } from '@nestjs/microservices';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.connectMicroservice<MicroserviceOptions>({
    transport: Transport.RMQ,
    options: {
      urls: ['amqp://guest:guest@localhost:5672'],
      queue: 'log-queue',
      queueOptions: { durable: true },
    },
  });

  await app.startAllMicroservices();
  await app.listen(3000);
}
bootstrap();

3️⃣ Implement a Log Producer (Send Logs to RabbitMQ):

import { Injectable } from '@nestjs/common';
import { ClientProxy, ClientProxyFactory, Transport } from '@nestjs/microservices';

@Injectable()
export class LogProducerService {
  private client: ClientProxy;

  constructor() {
    this.client = ClientProxyFactory.create({
      transport: Transport.RMQ,
      options: {
        urls: ['amqp://guest:guest@localhost:5672'],
        queue: 'log-queue',
        queueOptions: { durable: true },
      },
    });
  }

  sendLog(logMessage: string) {
    this.client.emit('log-event', logMessage);
  }
}

🔎 Implementing a Log Query API
To retrieve logs from the database, we need a Log API service. Here's a simple implementation using Spring Boot and PostgreSQL:

import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@RequestMapping("/logs")
public class LogQueryController {
    private final LogRepository logRepository;

    public LogQueryController(LogRepository logRepository) {
        this.logRepository = logRepository;
    }

    @GetMapping
    public List<LogEntry> getLogs() {
        return logRepository.findAll();
    }
}

🏁 Conclusion
By using AMQP (RabbitMQ) for logging, we achieve the following:

✅ Asynchronous log collection → Services send logs without blocking execution.
✅ Reliable processing → Logs are queued even if the consumer is down.
✅ Scalability → Multiple consumers can process logs in parallel.
✅ Decoupled log retrieval → A separate query API provides access to stored logs.

Would you like to see an integration with Grafana or Kibana for visualization? Let me know in the comments! 🚀