> 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/dependency-rules.md).

# Dependency Rules

## About

**Dependency Rules** define **which packages or layers are allowed to depend on others** in a Spring application. They ensure that **dependencies follow architectural guidelines**, prevent **tight coupling**, and reduce the risk of **cyclic dependencies**.

By controlling dependencies between layers, teams can enforce a **clean, modular architecture**, where each layer has a clear responsibility and can evolve independently without breaking other parts of the system.

## Purpose

The purpose of **Dependency Rules** is to enforce **controlled and predictable dependencies** between classes, packages, and layers in a Spring application.

Key objectives include:

1. **Prevent tight coupling**
   * Ensures layers or modules do not become overly dependent on each other, making the code easier to maintain and refactor.
2. **Avoid cyclic dependencies**
   * Prevents scenarios where two or more packages depend on each other, which can cause runtime issues, testing complications, and architectural drift.
3. **Maintain modularity and scalability**
   * By defining allowed dependencies, each layer or module can evolve independently, supporting better scalability and long-term maintainability.
4. **Support enforcement through tools**
   * Dependency rules can be automatically verified with ArchUnit or static analysis tools, catching violations early in development.
5. **Complement layered architecture and package rules**
   * While layered architecture defines the “what” of layers, dependency rules define the “how” classes and packages interact safely.

#### 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 (`api`)**

* Controllers **may depend on**:
  * Service (`service`) layer for business logic.
  * DTOs (`dto`) for request/response objects.
* Controllers **must not depend on**:
  * Repository (`repository`) or specification (`specification`) classes directly.
  * Entity (`entity`) classes directly.
  * Client (`client`) classes containing external business logic.

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

* Services **may depend on**:
  * Repository (`repository`) or specification (`specification`) for data access.
  * Client (`client`) for external API calls.
  * DTOs (`dto`) and mappers (`mapper`) for data transformations.
  * Utilities (`util`) for helper functions.
  * Configuration classes (`config`) containing properties loaded from .properties or .yaml file.
* Services **must not depend on**:
  * Controllers (`controller`) to prevent reverse dependencies.

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

* Repositories **may depend on**:
  * Entity (`entity`) classes.
  * Specification (`specification`) classes for query building.
* Repositories **must not depend on**:
  * Controllers (`controller`) or services (`service`).
  * DTOs (`dto`) or mappers (`mapper`).
  * Client (`client`) or utilities containing business logic.

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

* Entities **may depend on**:
  * Other entities for relationships.
  * Constants (`constants`) for enums and fixed values.
* Entities **must not depend on**:
  * Controllers (`controller`) or services (`service`).
  * Repositories (`repository`) or DTOs (`dto`).
  * Clients (`client`) or utilities containing business logic.

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

* DTOs **may depend on**:
  * Validation classes (`validation`).
* DTOs **must not depend on**:
  * Controllers (`controller`) or services (`service`).
  * Repositories (`repository`) or entities (`entity`).

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

* Mappers **may depend on**:
  * DTOs (`dto`) and entities (`entity`).
* Mappers **must not depend on**:
  * Services (`service`) or repositories (`repository`).
  * Controllers (`controller`) or clients (`client`).

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

* Clients **may depend on**:
  * DTOs (`dto`) for requests/responses.
  * Utilities (`util`) for HTTP handling, serialization, or logging.
* Clients **must not depend on**:
  * Services (`service`) or controllers (`controller`).
  * Repositories (`repository`) or entities (`entity`).

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

* Validators **may depend on**:
  * DTOs (`dto`) or entities (`entity`) they validate.
  * Utilities (`util`) for helper methods.
* Validators **must not depend on**:
  * Controllers (`controller`) or services (`service`).
  * Repositories (`repository`) or clients (`client`).

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

* Utilities **may be used by**:
  * Services, mappers, validation, and clients.
* Utilities **must not depend on**:
  * Services (`service`), controllers (`controller`), or repositories (`repository`).
  * Entities (`entity`) or DTOs (`dto`) containing business data.

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

* Exception classes **may depend on**:
  * Constants (`constants`) for error codes/messages.
* Exception classes **must not depend on**:
  * Controllers, services, repositories, or clients.

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

* Config classes **may depend on**:
  * Constants (`constants`) or utilities (`util`).
* Config classes **must not depend on**:
  * Controllers (`controller`), services (`service`), or repositories (`repository`).


---

# 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/dependency-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.