> For the complete documentation index, see [llms.txt](https://www.pranaypourkar.co.in/the-programmers-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pranaypourkar.co.in/the-programmers-guide/spring/best-practice/spring-coding-conventions/layered-architecture-rules.md).

# Layered Architecture Rules

## About

Layered architecture is a design pattern that **organizes code into distinct layers**, each with a specific responsibility. In Spring applications, this typically includes layers such as **Controller, Service, Repository, and Domain**.

The **Layered Architecture Rules** define how these layers should interact, which dependencies are allowed, and which are prohibited. By enforcing these rules, teams ensure that each layer **only communicates with appropriate layers**, reducing coupling and improving maintainability.

Layered architecture also promotes **separation of concerns**, making it easier to test, modify, and extend individual parts of the system without impacting others.

## Purpose

The purpose of **Layered Architecture Rules** is to enforce **consistent separation of responsibilities** within a Spring application and ensure that **dependencies between layers are well-defined**.

Key objectives include:

1. **Maintain clear boundaries between layers**
   * Controllers should only handle HTTP requests and delegate business logic to services.
   * Services should encapsulate business logic and orchestrate calls to repositories or other services.
   * Repositories should handle persistence and data access, without involving controllers or services directly.
2. **Reduce coupling and increase modularity**
   * Prevents layers from depending on inappropriate layers, which reduces the risk of tight coupling and circular dependencies.
3. **Enable easier testing and maintainability**
   * Layers with well-defined responsibilities can be **tested in isolation**.
   * Changes in one layer have minimal impact on others.
4. **Promote scalability and long-term architectural integrity**
   * Helps the system evolve while maintaining a predictable structure and avoiding architectural erosion.

#### Rules

Consider the following packaging structure

```
com.company.employeeportal
├── config                  # Spring and application configuration (DataSource, Swagger, CORS, etc.)
├── client                  # External API calls logic
├── constants               # Application-wide constants and enums
├── api                     # REST controllers for handling HTTP requests
├── dto                     # Data Transfer Objects for request/response bodies
├── entity                  # JPA entity classes (Employee, Department, Salary, etc.)
├── exception               # Custom exceptions and global exception handling
├── mapper                  # MapStruct or manual mappers (Entity <-> DTO)
├── repository              # Spring Data JPA repositories specification
├── specification           # Spring Data JPA specification 
├── service                 # Service classes for handling business logic
├── util                    # Utility/helper classes (DateUtils, PaginationUtils, etc.)
├── validation              # Custom validators and annotation-based rules
```

## **1. Controller Layer Rules (`api`)**

* Controllers must **only handle HTTP requests** and delegate business logic to the **service layer**.
* Controllers **must not**:
  * Directly access repositories or entities.
  * Call utility classes that perform business logic (util classes can only be helper functions like formatting or validation).
* Controllers **may** depend on:
  * DTOs (`dto`) for request/response binding.
  * Services (`service`) for business operations.
* Controllers **must not** throw repository-specific exceptions; exceptions should be handled via service layer or mapped to global exception handlers (`exception`).

## **2. Service Layer Rules (`service`)**

* Services contain **business logic** and orchestrate operations between repositories, external clients, and domain objects.
* Service classes **may depend on**:
  * Repositories (`repository`) for data access.
  * Specifications (`specification`) for complex queries.
  * DTOs (`dto`) and Mappers (`mapper`) for transforming data.
  * Utilities (`util`) for helper functions like formatting, pagination, or validation helpers.
  * Client (`client`) for external API calls.
  * Validation (`validation`) for any logic evaluation.
  * Configuration classes (`config`) containing properties loaded from .properties or .yaml file.
* Service classes **must not**:
  * Access controllers.
  * Depend on presentation-specific logic.
  * Depend on entities outside of repository or mapping context without proper encapsulation.

## **3. Repository Layer Rules (`repository`, `specification`)**

* Repositories handle **data access** using Spring Data JPA or custom specifications.
* Repositories **may depend on**:
  * Entities (`entity`) for persistence mapping.
  * Specifications (`specification`) for query building.
* Repositories **must not**:
  * Depend on controllers, services, DTOs, or clients.
  * Contain business logic; they are purely for CRUD and query operations.

## **4. Entity Layer Rules (`entity`)**

* Entities represent **domain models** and **database tables**.
* Entities **may depend on**:
  * Other entities (associations/relationships).
  * Constants (`constants`) for enum values.
* Entities **must not**:
  * Depend on controllers, services, repositories, or DTOs.
  * Include business logic beyond basic entity-level validation or constraints.

## **5. DTO Layer Rules (`dto`)**

* DTOs are for **data transfer between layers**, especially for controller inputs/outputs.
* DTOs **may depend on**:
  * Validation annotations (`validation`) if needed.
* DTOs **must not**:
  * Depend on services, repositories, or entities directly.
  * Contain business logic.

## **6. Mapper Layer Rules (`mapper`)**

* Mappers handle **conversion between DTOs and entities**.
* Mapper classes **may depend on**:
  * DTOs (`dto`) and entities (`entity`).
  * Utilities (`util`) for helper functions like formatting etc.
* Mapper classes **must not**:
  * Contain business logic.
  * Access services or repositories.

## **7. Client Layer Rules (`client`)**

* Client classes handle **external API calls**.
* Client classes **may depend on**:
  * DTOs for request/response objects.
  * Utilities (`util`) for HTTP formatting or serialization helpers.
* Client classes **must not**:
  * Call services or access repositories.
  * Contain business logic beyond API request/response orchestration.

## **8. Validation Layer Rules (`validation`)**

* Validators contain **custom validation logic** for entities or DTOs.
* Validation classes **may depend on**:
  * DTOs or entities they validate.
  * Utilities (`util`) for helper functions.
* Validation classes **must not**:
  * Access services, repositories, or controllers.
  * Include business orchestration logic.

## **9. Utility Layer Rules (`util`)**

* Utility classes provide **generic helper functions** (date formatting, pagination, string manipulation).
* Utilities **must not**:
  * Contain business logic.
  * Depend on services, controllers, or repositories.
* Utilities **may** be used by controllers, services, mappers, or validation classes.

## **10. Exception Layer Rules (`exception`)**

* Exception classes and global handlers define **application-level error management**.
* Exception classes **may depend on**:
  * Constants (`constants`) for error codes/messages.
* Exception classes **must not**:
  * Access services, repositories, or controllers directly.
  * Contain business logic.

## **11. Config Layer Rules (`config`)**

* Configuration classes manage Spring or application-level setup.
* Config classes **may depend on**:
  * Constants or properties.
  * Utility classes for reusable setup.
* Config classes **must not**:
  * Contain business logic.
  * Access controllers, services, or repositories.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://www.pranaypourkar.co.in/the-programmers-guide/spring/best-practice/spring-coding-conventions/layered-architecture-rules.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.