java-project-structure

Java Project Structure

Maven Single Module

com-yourorg-order-service/
├── src/
│   ├── main/
│   │   ├── java/com/yourorg/orderservice/
│   │   │   ├── OrderServiceApplication.java
│   │   │   ├── controller/
│   │   │   │   └── OrderController.java
│   │   │   ├── service/
│   │   │   │   └── OrderService.java
│   │   │   ├── repository/
│   │   │   │   └── OrderRepository.java
│   │   │   ├── model/
│   │   │   │   ├── Order.java
│   │   │   │   └── OrderStatus.java
│   │   │   ├── dto/
│   │   │   │   ├── CreateOrderRequest.java
│   │   │   │   └── OrderResponse.java
│   │   │   ├── exception/
│   │   │   │   ├── OrderNotFoundException.java
│   │   │   │   └── GlobalExceptionHandler.java
│   │   │   └── config/
│   │   │       └── SecurityConfig.java
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── application-dev.yml
│   │       └── db/migration/       # Flyway migrations
│   └── test/
│       └── java/com/yourorg/orderservice/
│           ├── controller/
│           ├── service/
│           └── repository/
├── pom.xml
├── Dockerfile
└── README.md

Package Conventions

• Reverse domain: com.yourorg.<servicename>
• One package per architectural layer: controller, service, repository, model, dto, exception, config
• No circular dependencies between packages
• Test packages mirror source packages

Multi-Module (Maven)

parent-pom/
├── pom.xml (parent)
├── api/pom.xml
├── application/pom.xml
├── domain/pom.xml
└── infrastructure/pom.xml

Build Conventions

• Maven: use spring-boot-starter-parent as parent POM
• Gradle: use io.spring.dependency-management plugin
• Pin Java version in pom.xml: <java.version>17</java.version>
• Use Flyway or Liquibase for DB migrations — never manual SQL