Layers & Separation of Concerns

Every backend you will ever work on is split into layers. Not because a framework demanded it, but because the alternative stops being editable at a few thousand lines. This lesson is the vocabulary for everything after it.

1. The problem layers solve

Imagine one file that receives the HTTP request, checks the password, decides whether the user is allowed, writes the SQL, formats the JSON, and sends the email. It works. Everyone starts here.

Then it stops working — not at runtime, but as a thing humans can change:

• You can't test any of it in isolation. Testing the password rule means starting a web server and a database.
• You can't change one thing safely. Swapping the email provider means editing a file that also contains your authorization logic.
• You can't read it. To answer "what happens when a task is created?" you read 900 lines and hold all of it in your head at once.
• Two people can't work on it. Every change touches the same file.

The two words that measure this are coupling (how much one piece depends on another) and cohesion (how much the things inside one piece belong together). You want low coupling between units and high cohesion inside them. Layering is the most common way to get there in a web backend.

2. The three layers

Almost every server-side web application — Spring, Rails, Django, ASP.NET, Express — lands on the same three responsibilities, whatever it calls them.

The rule that makes it work: dependency direction

Controllers depend on services. Services depend on repositories. Never the reverse. A repository must not know a controller exists; a service must not know whether it was called by HTTP, a scheduled job, or a test.

That one-way rule is what buys you the payoff. Because TodoService has no idea what HTTP is, a test can construct it with fake repositories and assert on business rules in milliseconds — no server, no database, no network.

The fourth thing: the DTO boundary

An entity is a class mapped to a database table. A DTO (Data Transfer Object) is a class shaped for the wire. Beginners return entities straight from controllers, and it always bites eventually:

• You leak fields you didn't mean to — a User entity has a passwordHash on it.
• Your API shape is now your table shape. Renaming a column becomes a breaking API change.
• Lazy-loading blows up during serialisation, at a point in the request where the database session may already be closed.

So the rule is: entities stay behind the service; the outside world sees DTOs.

3. In Studily: one feature, three files

Here is the whole pattern in your own codebase. The to-do feature is the newest one, so it is the cleanest example of the shape you settled on.

The controller knows only HTTP

// src/main/java/com/rnave/studily/todo/TodoController.java
@RestController
@RequestMapping("/api/todos")
public class TodoController {

    private final TodoService todoService;

    public TodoController(TodoService todoService) {
        this.todoService = todoService;
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public TodoDto create(@Valid @RequestBody TodoRequest req) {
        return todoService.create(req);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable Long id) {
        todoService.delete(id);
    }
}

Read what this file does not contain. No SQL. No ownership check. No transaction. No decision of any kind. Its entire job is: map a URL and a verb to a method, validate the shape of the incoming JSON (@Valid), pick the right status code, hand off.

That's about 60 lines for five endpoints. When a controller starts growing, it's almost always because a decision has crept in that belongs one layer down.

The service makes the decisions

// src/main/java/com/rnave/studily/todo/TodoService.java
@Service
public class TodoService {

    @Transactional
    public TodoDto update(Long id, TodoRequest req) {
        Todo todo = requireOwned(id);      // authorization
        apply(todo, req);                  // business rules
        return TodoDto.from(todoRepository.save(todo));   // entity -> DTO
    }

    @Transactional(readOnly = true)
    public Todo requireOwned(Long id) {
        return todoRepository.findByIdAndUserId(id, currentUser.id())
                .orElseThrow(() -> new NotFoundException("Task not found"));
    }
}

Four distinct responsibilities live here, and all four are things a controller must not do:

The repository is an interface with no body

// src/main/java/com/rnave/studily/todo/TodoRepository.java
public interface TodoRepository extends JpaRepository<Todo, Long> {

    List<Todo> findByUserId(Long userId);

    Optional<Todo> findByIdAndUserId(Long id, Long userId);

    List<Todo> findByUserIdAndCompletedAtIsNullAndDueAtBetweenOrderByDueAtAsc(
            Long userId, Instant from, Instant to);
}

There is no implementation. Spring Data reads the method names and generates the SQL: findByIdAndUserId becomes WHERE id = ? AND user_id = ?. That's a framework convenience, but the layering point stands on its own — the repository's only job is "get me rows", and it holds no opinion about what they mean.

4. Where your own code breaks the rule

This is the part that turns a memorised pattern into something you actually understand. Two features in Studily do not have a service layer: notes and calendar. Both put @Transactional directly on the controller.

That was a deliberate decision, and the interesting bit is that it has aged differently in the two cases.

Notes: still fine

NoteController is about 72 lines for three endpoints. The only business logic in the entire feature is a trim(). A service class here would be three methods that forward straight through to the repository — pure ceremony, more files to open, nothing gained.

Calendar: has outgrown it

CalendarController started the same way. It is now around 155 lines and contains category resolution, recurrence expansion, and series-scoped update and delete:

// CalendarController — business logic that drifted into the wrong layer
@PutMapping("/events/{id}")
@Transactional
public CalendarEventDto updateEvent(@PathVariable Long id,
                                    @RequestParam(defaultValue = "OCCURRENCE") SeriesScope scope,
                                    @Valid @RequestBody CalendarEventRequest req) {
    CalendarEvent event = eventRepository.findByIdAndUserId(id, currentUser.id())
            .orElseThrow(() -> new NotFoundException("Event not found"));
    EventCategory category = resolveCategory(req.categoryId());

    for (CalendarEvent target : scopeOf(event, scope)) {   // <-- fan-out over a whole series
        ...
    }
}

And here is the sharp edge: the academic item side of the identical feature — repeating assignments, with the exact same series-scope logic — lives in AcademicItemService. So one behaviour is implemented at two different layers depending on which entity it acts on.

5. Beyond three layers (what's next in the industry)

You will hear other architecture names in interviews. You don't need to have used them, but recognising them and knowing what problem they solve is worth a lot.

6. Say it out loud

7. Module quiz

Eight questions. 80% or better means move on; below 50% means reread sections 2 and 3.

8. Take-aways