🧠 From Chaos to Clean Code: My Java Refactor Journey - Part 3 of 6

Now that we’ve separated concerns and cleaned up the code, it’s time for the next step:
introducing Clean Architecture layers and applying DDD concepts with proper domain modeling.

Let’s make the design clearer, scalable, and truly domain-focused. 🚀

🔧 Step 1: Laying the Groundwork for Clean Architecture

Before we can apply Clean Architecture and DDD properly, we need to rethink our folder structure.

Right now, everything is grouped by technical role:

com.example.spaghetti
├── controller
│   └── ThingController.java
│   └── ItemController.java
├── service
│   └── ThingService.java
│   └── ItemService.java
├── repository
│   └── ThingRepository.java
│   └── ItemRepository.java
├── model
│   └── Thing.java
│   └── Item.java
├── config
│   └── MainConfig.java
├── util
│   └── Utils.java

That’s a good start — but Clean Architecture is not just about naming layers, it’s about isolating responsibilities and controlling dependencies between them.

✅ 1. Define the main layers
Here’s the structure we’re aiming for:

com.example.spaghetti
├── domain           ← business rules and core entities (pure Java)
├── application      ← use cases (calls domain logic)
├── infrastructure   ← technical details (config, persistence, utilities)
├── adapter          ← I/O layers (controllers, REST APIs, DTOs)

💡 Rule of thumb:

• Domain is the core.
• Application uses the domain.
• Infrastructure supports them.
• Adapter is how the outside world talks to the app.

✅ 2. Move your classes to the right packages
Let’s organize your existing code into those layers:

🔹 domain
Core entities and domain contracts

com.example.spaghetti.domain.model
  └── Thing.java
  └── Item.java

com.example.spaghetti.domain.repository
  └── ThingRepository.java
  └── ItemRepository.java

🔹 application
Business coordination logic

com.example.spaghetti.application.service
  └── ThingService.java
  └── ItemService.java

🔹 infrastructure
Low-level details like config and utility classes

com.example.spaghetti.infrastructure.config
  └── MainConfig.java

com.example.spaghetti.infrastructure.util
  └── Utils.java

🔹 adapter
Web interface and DTOs

com.example.spaghetti.adapter.controller
  └── ThingController.java
  └── ItemController.java

com.example.spaghetti.adapter.dto
  └── (we'll add DTOs in the next steps)

This new structure aligns your code with Clean Architecture principles, making it easier to scale, test, and evolve over time.

🔧 Step 2: Introducing DTOs, Mappers, and Validation for Clear Separation

After reorganizing our project structure and separating concerns, the next essential step was to make the boundary between our API and domain logic explicit — by introducing DTOs (Data Transfer Objects), validation, and mappers.

📂 Organizing DTOs and Mappers
We created dedicated packages to keep the code clean and scalable:

com.example.spaghetti.adapter.dto.request    ← Input DTOs (ThingRequest, ItemRequest)
com.example.spaghetti.adapter.dto.response   ← Output DTOs (ThingResponse, ItemResponse)
com.example.spaghetti.adapter.dto.mapper     ← Mappers to convert between DTOs and domain entities

This separation keeps the API contract clear, prevents domain leakage, and isolates transformations, following Clean Architecture’s adapter layer principle.

📄 Why DTOs?
DTOs define exactly what data enters and leaves our system. To ensure data integrity, we added validation annotations from Jakarta Validation API, such as NotBlank and NotNull, on the request DTO fields.

This guarantees that only valid and well-formed data reaches the business logic layer.

By doing this, our domain entities remain clean and focused solely on business rules — an important DDD principle to avoid coupling domain models to external layers.

🛠️ Using MapStruct for Mapping
To avoid boilerplate code when converting between DTOs and entities, we introduced MapStruct, a code generator that creates type-safe mappers automatically:

@Mapper(componentModel = "spring")
public interface ThingMapper {
    Thing toEntity(ThingRequest request);
    ThingResponse toResponse(Thing thing);
    List<ThingResponse> toResponse(List<Thing> things);
}

@Mapper(componentModel = "spring")
public interface ItemMapper {
    Item toEntity(ItemRequest request);
    ItemResponse toResponse(Item item);
    List<ItemResponse> toResponseList(List<Item> things);
}

Mappers live in the adapter layer and keep our domain pure from external concerns.

⚙️ Controller Adjustments
Controllers were updated to:

• Accept validated request DTOs (annotated with Jakarta Validation constraints)
• Use mappers to convert requests into domain entities
• Call the service layer with domain entities
• Convert service results back into response DTOs for the client
• This keeps the controller’s responsibility to a simple orchestrator — no business logic inside, fully aligned with Clean Architecture.

✅ What this achieved

• Clear separation of API and domain models
• Early validation of input data via Jakarta Validation annotations
• Reduced boilerplate with MapStruct generated code
• Improved maintainability and scalability of the codebase

🧠 What’s next?

With DTOs, validation, and mapping in place, our code is now clean, scalable, and aligned with Clean Architecture and DDD principles.
Next up, we’ll focus on improving reliability by implementing global error handling and writing unit tests.