Lesson 22 of 23

In progress

Course progress

Java

Structuring a Java project

Lay out packages by feature, separate the domain from the plumbing, and keep main small so the capstone has a shape to follow.

A project layout is a promise about where things live. Good layouts make a change local; bad ones make every change a tour of the codebase.

What you will learn

  • Choose a package structure that survives growth.
  • Separate domain logic from input and storage.
  • Keep the entry point thin.

Start from the build layout

/src/main/java/com/example/library/
App.java
domain/
Book.java
Loan.java
Member.java
service/
LoanService.java
storage/
BookRepository.java
InMemoryBookRepository.java
cli/
Menu.java
/src/test/java/com/example/library/
service/LoanServiceTest.java

That is the standard Maven or Gradle layout with three internal packages. domain holds the rules, service orchestrates, storage and cli are the edges.

Packages by feature, not by layer

domain, service and storage are layers, which is a reasonable starting point for a small application. The alternative is feature packages:

com/example/library/loans/
com/example/library/catalogue/
com/example/library/members/

Each feature package holds its own domain types, service and storage access. A change to loans touches one folder, and a new contributor can find the code by the word they use to describe the feature.

Layer packaging tends to produce service/ folders with forty classes that have nothing to do with each other. If that happens, switch to feature packaging; the refactor is mechanical with an IDE.

The domain depends on nothing

package com.example.library.domain;
public record Loan(long bookId, long memberId, String borrowedOn, String dueOn) {
public Loan {
if (dueOn.compareTo(borrowedOn) < 0) {
throw new IllegalArgumentException("due before borrowed");
}
}
public boolean isOverdue(String today) {
return dueOn.compareTo(today) < 0;
}
}

Loan uses only the language and the standard library. No database, no console, no file paths. That makes it testable with a constructor and readable without knowing the application.

Keeping the domain free of infrastructure is the single most valuable structural decision in a small project. It is also what allows the storage to be swapped without touching the rules.

Ports at the edges

package com.example.library.storage;
public interface LoanRepository {
void save(Loan loan);
java.util.List<Loan> openLoans();
}

The service depends on the interface, not the implementation. A test provides an in-memory version; production provides a file or database version. Neither the service nor the domain knows which.

package com.example.library.service;
public class LoanService {
private final LoanRepository repository;
public LoanService(LoanRepository repository) {
this.repository = repository;
}
public void borrow(Loan loan) {
repository.save(loan);
}
}

The constructor takes the dependency rather than creating it. That is dependency injection without a framework, and for most small applications it is all you need.

A thin entry point

package com.example.library;
public class App {
public static void main(String[] args) {
var repository = new com.example.library.storage.FileLoanRepository("data/loans.csv");
var service = new com.example.library.service.LoanService(repository);
new com.example.library.cli.Menu(service).run();
}
}

main wires the objects and starts the interface. It contains no rules and no formatting, so changing the input from console to HTTP would replace cli and leave everything else alone.

When main grows past twenty lines, logic is leaking into it.

Errors at the boundary

The service throws exceptions that describe domain failures. The CLI catches them and prints a message a user can act on. The domain never prints, and the CLI never decides a rule.

That separation is why the same service can serve a console application, a web endpoint and a test with no changes.

Tests mirror the structure

src/test/java/com/example/library/domain/LoanTest.java
src/test/java/com/example/library/service/LoanServiceTest.java

A test lives in the package of the class it tests, which is why a package-private method can still be tested: the test is inside the package but in a different source root.

If a class is hard to test, the structure is usually the reason: a constructor that opens a file, a static call to System.currentTimeMillis, a method that both reads and formats. Moving that dependency behind a parameter fixes the test and the design at the same time.

What goes where

  • Records and classes with rules: domain.
  • Coordination of several domain objects: service.
  • Anything that talks to the outside world: an edge package.
  • Shared utilities: rarely, and named by what they do rather than Util.

A package called util is where clarity goes to die. If two classes share a helper, put it next to them, or make it a method on the type that owns the concept.

Putting SQL or file parsing inside a domain class because it was convenient. The class then needs a database to be tested, and the rule cannot be reused elsewhere.

Sketch a package layout for a task tracker with tasks, users and a JSON file store, naming four packages and the dependency direction between them.

Show solution
com/example/tasks/ App.java domain/Task.java domain/User.java service/TaskService.java storage/TaskRepository.java storage/JsonTaskRepository.java cli/Menu.java

Dependencies point inward: cli and storage depend on service and domain; service depends on domain and the repository interface; domain depends on nothing. That direction is what lets the JSON store be replaced by a database, or the CLI by an HTTP layer, without touching the rules.

Recap

  • Use the build layout and choose packages by feature once layer folders stop being cohesive.
  • Keep the domain free of infrastructure and put ports at the edges.
  • Wire everything in a thin main, and mirror the structure in tests.

The capstone puts all of this together in a console application.

How many classes should a package have?
No fixed number. If names in a folder no longer share a theme, it is probably two packages.
Do I need a framework?
Not for structure. Dependency injection by constructor works without one; adopt a framework when it removes real work.

Progress is saved in this browser only. No account, no email.

Admin

About the author

Admin

Instructor and technical writer at tutorials.in

Writes beginner lessons for tutorials.in. Each lesson is checked against the language or tool documentation, and examples are run before publishing.

Reviewed by the editorial team before publishing. Last updated November 16, 2026.