Clean Architecture Applied to Java APIs

Modern backend systems tend to grow quickly. What starts as a simple API can become a complex system with dozens of services, integrations, and business rules.

Without proper structure, it’s common to see projects where:

• Controllers contain business logic

• Services grow into massive classes

• Infrastructure concerns leak into domain logic

This is where Clean Architecture becomes extremely valuable.

The concept was popularized by Robert C. Martin and focuses on creating systems that are:

• Maintainable

• Testable

• Independent of frameworks

• Easy to evolve

In this article, we’ll explore how to apply Clean Architecture when building Java APIs with Spring Boot.

What is Clean Architecture?

Clean Architecture organizes software into layers with clear responsibilities.

The key idea is simple:

Business logic should not depend on frameworks or external technologies.

Instead, frameworks should depend on your business logic.

Core Layers

The architecture is typically divided into four main layers:

1. Entities

2. Use Cases

3. Interface Adapters

4. Frameworks & Drivers

See the diagram below:

Each layer moves from high-level business rules to low-level technical details.

The Most Important Rule: Dependency Rule

Clean Architecture enforces one fundamental rule:

Dependencies must always point inward.

This means:

• Outer layers depend on inner layers

• Inner layers must not know about outer layers

Visual representation:

This rule ensures that your core business logic remains independent from external frameworks like Spring, databases, or messaging systems.

Applying Clean Architecture in a Java API

A typical project structure might look like this:

Let’s explore each layer.

1. Domain Layer (Entities)

The domain layer contains the core business rules of the application.

Important characteristics:

• No framework dependencies

• Pure Java classes

• Business logic lives here

Example:

Notice that:

• There is no Spring dependency

• The business rule is inside the entity

  
  

2. Application Layer (Use Cases)

Use cases represent specific actions the system can perform.

Examples:

Example implementation:

Key points:

• The use case orchestrates the business logic

• It depends on interfaces, not implementations

3. Interface Adapters

This layer adapts the outside world to the application.

Examples include:

• REST Controllers

• DTOs

• Mappers

  
  

Example controller:

The controller only:

• Receives the request

• Delegates to the use case

No business rules here.

4. Infrastructure Layer

This is where framework-specific code lives.

Examples:

• Spring Boot configuration

• Database access

• External APIs

• Messaging systems

Example repository implementation:

This class depends on Spring, but the domain does not depend on it.

Request Flow in a Clean Architecture API

When a request reaches the API, the flow typically looks like this:

1. Controller receives the HTTP request

2. Controller calls the Use Case

3. Use Case executes business logic

4. Repository retrieves or saves data

5. Database persists the data

Diagram:

Benefits of Clean Architecture

1. Testability

Use cases can be tested without Spring Boot.

Example:

• JUnit

• Mockito

No need to start the application context.

2. Framework Independence

Your core logic does not depend on Spring.

If needed, you could move from:

without rewriting your business logic.

3. Better Maintainability

Each layer has a clear responsibility:

Layer	Responsibility
Domain	Business rules
Application	Use cases
Adapters	Interface translation
Infrastructure	Technical details

4. Long-Term Scalability

Large projects remain easier to maintain as the codebase grows.

When Should You Use Clean Architecture?

Clean Architecture works best for:

• Systems with complex business logic

• Long-term projects

• Large teams

• APIs expected to evolve over time

For very small services, it may introduce unnecessary complexity.

Conclusion

Clean Architecture is not just a pattern for organizing code — it’s a mindset for building sustainable software systems.

By keeping your domain independent from frameworks, you create APIs that are:

• Easier to test

• Easier to maintain

• Easier to evolve

When applied properly in Java APIs with Spring Boot, Clean Architecture helps teams build systems that can grow without becoming unmanageable.