Refactor course module to ports and adapters architecture

Author: gabriele.sisinna

README.md

@@ -5,6 +5,15 @@ This project is built so you can learn, test, and modify small examples instead
 Full repo learning notes are in [docs/README.md](./docs/README.md).
 Deployment notes and production files are in [deploy/README.md](./deploy/README.md).
 
+## Software architecture
+
+The repo now teaches two architectural styles:
+
+- a simple layered flow for the student example
+- a ports-and-adapters style for the course example
+
+Read [docs/architecture.md](./docs/architecture.md) for the design rationale and package boundaries.
+
 ## What this repo teaches
 
 ### Plain Java
@@ -50,10 +59,13 @@ Read these files in order:
 5. `src/main/java/com/example/demo/basics/generics/Box.java`
 6. `src/main/java/com/example/demo/basics/streams/StudentAnalytics.java`
 7. `src/main/java/com/example/demo/spring/service/StudentService.java`
-8. `src/main/java/com/example/demo/spring/persistence/service/CourseService.java`
-9. `src/main/java/com/example/demo/spring/persistence/controller/CourseController.java`
-10. `src/main/java/com/example/demo/spring/config/AppLearningProperties.java`
-11. `src/test/java/com/example/demo/spring/persistence/controller/CourseControllerTest.java`
+8. `src/main/java/com/example/demo/spring/persistence/domain/Course.java`
+9. `src/main/java/com/example/demo/spring/persistence/service/CourseService.java`
+10. `src/main/java/com/example/demo/spring/persistence/service/CourseApplicationService.java`
+11. `src/main/java/com/example/demo/spring/persistence/store/MongoCourseStore.java`
+12. `src/main/java/com/example/demo/spring/persistence/controller/CourseController.java`
+13. `src/main/java/com/example/demo/spring/config/AppLearningProperties.java`
+14. `src/test/java/com/example/demo/spring/persistence/controller/CourseControllerTest.java`
 
 ## Package guide
 
@@ -80,7 +92,7 @@ Read these files in order:
 - `com.example.demo.spring.model`
   - request and response models
 - `com.example.demo.spring.persistence`
-  - validation, MongoDB documents, JSON APIs, and security examples
+  - validation, MongoDB documents, layered architecture, and security examples
 - `com.example.demo.spring.config`
   - OpenAPI config and typed configuration properties
 

docs/README.md

@@ -6,11 +6,12 @@ This folder explains how to use the repository as a guided Java and Spring Boot
 
 1. [Learning Path](./learning-path.md)
 2. [Repo Map](./repo-map.md)
-3. [Java Basics](./java-basics.md)
-4. [Spring Boot](./spring-boot.md)
-5. [Testing](./testing.md)
-6. [Tooling](./tooling.md)
-7. [Deployment](./deployment.md)
+3. [Architecture](./architecture.md)
+4. [Java Basics](./java-basics.md)
+5. [Spring Boot](./spring-boot.md)
+6. [Testing](./testing.md)
+7. [Tooling](./tooling.md)
+8. [Deployment](./deployment.md)
 
 ## Main idea
 

docs/architecture.md

@@ -0,0 +1,119 @@
+# Architecture Guide
+
+This repo uses two architectural levels on purpose:
+
+- a simple layered flow for the student example
+- a more explicit ports-and-adapters flow for the course example
+
+That split is intentional for learning. You can start with the simpler version and then see how a more maintainable design looks when persistence and security become more important.
+
+## High-level structure
+
+```text
+HTTP request
+  -> controller
+  -> use-case interface
+  -> application service
+  -> store interface
+  -> Mongo adapter
+  -> Spring Data repository
+  -> MongoDB
+```
+
+For responses, the flow goes back in the opposite direction, with the controller mapping domain objects into response DTOs.
+
+## Why the course module is more structured
+
+The student flow is intentionally small and direct so beginners can learn controller/service/repository basics first.
+
+The course flow uses stronger boundaries because it is the better example for long-term maintainability:
+
+- the controller should not know MongoDB details
+- the application service should not depend on web DTOs
+- the domain model should not depend on Spring Data classes
+- persistence-specific mapping should live in the adapter layer
+
+This keeps each layer focused on one job.
+
+## Main patterns used
+
+### Layered architecture
+
+The repo still follows a familiar layered shape:
+
+- controller layer
+- service/application layer
+- persistence layer
+
+That makes the code easy to navigate.
+
+### Dependency inversion
+
+The application service depends on `CourseStore`, not on `MongoRepository`.
+
+That means the core use case depends on an interface, and the Mongo adapter implements it. This is the main architectural improvement in the repo.
+
+### Ports and adapters
+
+The course module uses a lightweight hexagonal style:
+
+- input port: `CourseService`
+- output port: `CourseStore`
+- adapter: `MongoCourseStore`
+
+This is useful because it makes framework code replaceable instead of central to the core logic.
+
+### Repository pattern
+
+`CourseRepository` is the Spring Data repository for MongoDB.
+
+It is not used directly by the controller or application service anymore. It sits behind `MongoCourseStore`.
+
+### Mapper pattern
+
+There are two kinds of translation in the course module:
+
+- controller maps request DTOs into application commands and domain objects into response DTOs
+- `CourseDocumentMapper` maps domain objects into Mongo documents and back
+
+This avoids leaking transport or database concerns across layers.
+
+## Package roles in the course module
+
+- `spring.persistence.domain`
+  - framework-independent domain model
+- `spring.persistence.service`
+  - input port and application service
+- `spring.persistence.store`
+  - output port and Mongo adapter
+- `spring.persistence.document`
+  - MongoDB document classes
+- `spring.persistence.repository`
+  - Spring Data repository interfaces
+- `spring.persistence.controller`
+  - HTTP entry points and request/response mapping
+
+## Why this is better than the previous version
+
+Before the refactor:
+
+- the service knew about request DTOs
+- the service returned response DTOs
+- the service depended directly on the Mongo repository
+
+After the refactor:
+
+- the controller owns HTTP DTO mapping
+- the service owns use-case logic
+- the store adapter owns persistence translation
+- the domain model stays free of Spring and Mongo classes
+
+That is a cleaner separation of responsibilities.
+
+## Tradeoff
+
+This architecture adds more files.
+
+That is the cost of clearer boundaries.
+
+For a tiny project, that would sometimes be too much. For a learning repo, it is useful because it shows what "better architecture" actually looks like in code rather than only describing it in theory.

docs/learning-path.md

@@ -73,17 +73,23 @@ Learn:
 Read:
 
 - `spring/persistence/model/CreateCourseRequest.java`
+- `spring/persistence/domain/Course.java`
 - `spring/persistence/document/CourseDocument.java`
 - `spring/persistence/repository/CourseRepository.java`
+- `spring/persistence/store/CourseStore.java`
+- `spring/persistence/store/MongoCourseStore.java`
 - `spring/persistence/config/CourseDataInitializer.java`
 - `spring/persistence/service/CourseService.java`
+- `spring/persistence/service/CourseApplicationService.java`
 - `spring/persistence/controller/CourseController.java`
 - `spring/security/SecurityConfig.java`
 
 Learn:
 
 - validation with `@Valid`
 - constraints like `@NotBlank` and `@Min`
+- domain model vs persistence model
+- input port vs output port
 - MongoDB document mapping
 - JSON request/response flow
 - basic auth with Spring Security

docs/repo-map.md

@@ -39,14 +39,18 @@ This page explains why each package exists.
 
 ## Spring persistence packages
 
+- `spring.persistence.domain`
+  - framework-independent business model
 - `spring.persistence.document`
   - MongoDB document classes
 - `spring.persistence.repository`
-  - Spring Data repository interfaces
+  - Spring Data repository interfaces used only by the adapter
 - `spring.persistence.config`
   - seed data and persistence bootstrap
 - `spring.persistence.service`
-  - business logic using the repository layer
+  - input port and application service
+- `spring.persistence.store`
+  - output port plus MongoDB adapter and mapper
 - `spring.persistence.controller`
   - secured HTTP endpoints
 - `spring.persistence.model`

docs/spring-boot.md

@@ -3,7 +3,7 @@
 This repo contains two Spring learning tracks:
 
 - a simple in-memory student API
-- a more realistic secured course API with validation and persistence
+- a more realistic secured course API with validation, persistence, and explicit architectural boundaries
 
 ## Spring Boot structure
 
@@ -19,6 +19,14 @@ This repo shows both:
 - simple flow with in-memory data
 - document-backed flow with MongoDB
 
+The course module also shows a stronger architecture:
+
+- controller
+- use-case interface
+- application service
+- store interface
+- MongoDB adapter
+
 ## Controllers
 
 Examples:
@@ -46,6 +54,7 @@ Examples:
 
 - `StudentService`
 - `CourseService`
+- `CourseApplicationService`
 
 Service responsibilities:
 
@@ -70,6 +79,7 @@ Why it matters:
 - easier testing
 - clearer dependencies
 - better separation of responsibilities
+- support for dependency inversion through interfaces
 
 ## Request and response models
 
@@ -138,15 +148,21 @@ Handled cases include:
 
 Main files:
 
+- `Course`
 - `CourseDocument`
 - `CourseRepository`
+- `CourseStore`
+- `MongoCourseStore`
 - `application.yml`
 - `CourseDataInitializer`
 
 Key ideas:
 
+- `Course` is the framework-independent domain model
 - `@Document` maps a class to a MongoDB collection
 - a `MongoRepository` gives CRUD operations
+- `CourseStore` is the output port used by the application service
+- `MongoCourseStore` is the adapter that hides Spring Data details
 - `CourseLevel` enum keeps the `level` field restricted to valid values
 - MongoDB stores JSON-like documents instead of rows
 - `CourseDataInitializer` seeds example documents at startup

docs/testing.md

@@ -33,7 +33,7 @@ What they teach:
 
 - behavior-focused assertions
 - testing single classes
-- mocking with Mockito in `CourseServiceTest`
+- mocking ports and adapters with Mockito in `CourseServiceTest`
 
 ## Configuration tests
 
@@ -65,6 +65,7 @@ What they teach:
 - JSON assertions
 - authentication testing with `httpBasic(...)`
 - documentation endpoint checks
+- controller testing against a use-case interface instead of a concrete implementation
 
 ## How to read a test well
 

src/main/java/com/example/demo/spring/persistence/config/CourseDataInitializer.java

@@ -1,8 +1,8 @@
 package com.example.demo.spring.persistence.config;
 
-import com.example.demo.spring.persistence.document.CourseDocument;
+import com.example.demo.spring.persistence.domain.Course;
 import com.example.demo.spring.persistence.model.CourseLevel;
-import com.example.demo.spring.persistence.repository.CourseRepository;
+import com.example.demo.spring.persistence.store.CourseStore;
 import org.springframework.boot.CommandLineRunner;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.context.annotation.Bean;
@@ -14,14 +14,14 @@ public class CourseDataInitializer {
 
 	@Bean
 	@ConditionalOnProperty(name = "app.courses.seed.enabled", havingValue = "true", matchIfMissing = true)
-	CommandLineRunner seedCourses(CourseRepository courseRepository) {
+	CommandLineRunner seedCourses(CourseStore courseStore) {
 		return args -> {
-			if (courseRepository.count() > 0) {
+			if (!courseStore.isEmpty()) {
 				return;
 			}
 
-			courseRepository.save(new CourseDocument("Java Generics Deep Dive", CourseLevel.INTERMEDIATE, 6, true));
-			courseRepository.save(new CourseDocument("Spring Boot REST APIs", CourseLevel.BEGINNER, 5, true));
+			courseStore.save(new Course(null, "Java Generics Deep Dive", CourseLevel.INTERMEDIATE, 6, true));
+			courseStore.save(new Course(null, "Spring Boot REST APIs", CourseLevel.BEGINNER, 5, true));
 		};
 	}
 }