> 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/package-and-class-location-rules.md).

# Package & Class Location Rules

## About

**Package & Class Location Rules** define how classes should be **organized within the project’s package structure**. Proper organization improves **readability, maintainability, and modularity**.

In Spring projects, packages often reflect **functional or architectural separation**, such as `controller`, `service`, `repository`, `entity`, `dto`, `mapper`, and `util`. Enforcing these rules ensures that:

* Classes are **predictably placed** based on their role.
* Developers can **quickly locate relevant classes**.
* Tools like ArchUnit or static analyzers can **validate package conventions**.

These rules complement **layered architecture rules** by providing **physical structure guidance**, ensuring that classes not only follow proper dependencies but also reside in the correct locations within the project.

## Purpose

The purpose of **Package & Class Location Rules** is to enforce **consistent placement of classes within the project structure**, ensuring that the package organization reflects the **role and responsibility** of each class.

Key objectives include:

1. **Improve project readability and navigation**
   * Developers can easily find classes based on package names, reducing time spent searching for code.
2. **Support maintainability and modularity**
   * By keeping related classes together and separating unrelated components, the codebase becomes easier to maintain and extend.
3. **Enable automated validation**
   * Tools like ArchUnit can verify that classes are correctly placed, reducing errors introduced during development or refactoring.
4. **Reinforce architectural rules**
   * Proper package placement complements layered architecture rules, ensuring that dependencies align with physical structure.
5. **Facilitate team collaboration**
   * A predictable structure ensures that multiple developers working on the same project follow the same conventions, making code reviews and onboarding smoother.

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

* Classes annotated with `@RestController` or containing `Controller` in their name must reside in the `controller` package.
* Controllers **must not** be placed in `service`, `repository`, or `entity` packages.

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

* All business logic classes should reside in the `service` package.
* Services **must not** be placed in `controller`, `repository`, or `entity` packages.

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

* Repository interfaces and Spring Data JPA specifications must reside in `repository` or `specification` packages.
* Repositories **must not** reside in `service`, `controller`, or `entity` packages.

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

* JPA entity classes must reside in the `entity` package.
* Entities **must not** be placed in `controller`, `service`, or `repository` packages.

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

* DTOs for requests and responses must reside in the `dto` package.
* DTOs **must not** be placed in `service`, `repository`, or `entity` packages.

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

* Mapper classes should reside in the `mapper` package.

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

* Classes handling external API calls must reside in the `client` package.
* Clients **must not** reside in `service`, `controller`, or `repository`.

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

* Custom validators must reside in the `validation` package.

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

* Generic helper classes must reside in the `util` package.

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

* Custom exceptions and global exception handlers must reside in the `exception` package.
* Exceptions **must not** reside in service, controller, or repository packages.

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

* Spring or application configuration classes must reside in the `config` package.


---

# 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/package-and-class-location-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.