Add structured learning documentation

Author: gabriele.sisinna

README.md

@@ -2,6 +2,8 @@
 
 This project is built so you can learn, test, and modify small examples instead of reading a large codebase.
 
+Full repo learning notes are in [docs/README.md](./docs/README.md).
+
 ## What this repo teaches
 
 ### Plain Java
@@ -15,6 +17,10 @@ This project is built so you can learn, test, and modify small examples instead
 - exceptions
 - packages
 - annotations
+- interfaces
+- inheritance and polymorphism
+- generics
+- streams and lambdas
 
 ### Spring Boot
 
@@ -24,16 +30,25 @@ This project is built so you can learn, test, and modify small examples instead
 - request/response model
 - Swagger UI
 - OpenAPI YAML
+- validation
+- JPA + H2 persistence
+- basic authentication with Spring Security
+- unit, repository, and integration tests
 
 ## Start here
 
 Read these files in order:
 
 1. `src/main/java/com/example/demo/basics/model/Student.java`
 2. `src/test/java/com/example/demo/basics/model/StudentTest.java`
-3. `src/main/java/com/example/demo/spring/service/StudentService.java`
-4. `src/main/java/com/example/demo/spring/controller/StudentController.java`
-5. `src/test/java/com/example/demo/spring/controller/StudentControllerTest.java`
+3. `src/main/java/com/example/demo/basics/interfaces/Notifier.java`
+4. `src/main/java/com/example/demo/basics/inheritance/LearningStudent.java`
+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/test/java/com/example/demo/spring/persistence/controller/CourseControllerIntegrationTest.java`
 
 ## Package guide
 
@@ -43,6 +58,14 @@ Read these files in order:
   - custom exception example
 - `com.example.demo.basics.model`
   - plain Java class with fields, constructors, methods, `if`, `for`, `List`, and `Map`
+- `com.example.demo.basics.interfaces`
+  - interface and implementation examples
+- `com.example.demo.basics.inheritance`
+  - inheritance and polymorphism examples
+- `com.example.demo.basics.generics`
+  - generic class example
+- `com.example.demo.basics.streams`
+  - streams and lambda-style collection processing
 - `com.example.demo.spring.repository`
   - in-memory data storage
 - `com.example.demo.spring.service`
@@ -51,6 +74,8 @@ Read these files in order:
   - HTTP endpoints and error handling
 - `com.example.demo.spring.model`
   - request and response models
+- `com.example.demo.spring.persistence`
+  - validation, JPA, H2, and security examples
 
 ## Run the app
 
@@ -72,6 +97,7 @@ Then open:
 
 - `http://localhost:8080/api/students`
 - `http://localhost:8080/swagger-ui.html`
+- `http://localhost:8080/h2-console`
 
 To stop it:
 
@@ -110,6 +136,25 @@ curl -X POST http://localhost:8080/api/students \
   }'
 ```
 
+Get secured courses with basic auth:
+
+```bash
+curl -u student:password http://localhost:8080/api/courses
+```
+
+Create a secured database-backed course:
+
+```bash
+curl -u student:password -X POST http://localhost:8080/api/courses \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Spring Data JPA",
+    "level": "intermediate",
+    "durationInHours": 7,
+    "published": true
+  }'
+```
+
 ## Swagger and OpenAPI
 
 After starting the app with `./gradlew bootRun`, open:
@@ -144,6 +189,12 @@ Run the tests inside a container:
 docker compose run --rm test
 ```
 
+Different test layers in this repo:
+
+- unit tests: small classes without Spring, such as `StudentTest` and `CourseServiceTest`
+- repository tests: JPA + H2 with a Spring Boot integration test, such as `CourseRepositoryTest`
+- integration tests: full Spring Boot + MockMvc, such as `StudentControllerTest` and `CourseControllerIntegrationTest`
+
 ## GitHub CI
 
 This repo includes a GitHub Actions workflow at `.github/workflows/ci.yml`.
@@ -160,7 +211,8 @@ It runs on every push and pull request, sets up Java 17, and executes:
 2. In `Student.java`, add another method such as `averageScore()`.
 3. In `StudentService.java`, change how new students are created.
 4. In `StudentController.java`, add a new endpoint such as `DELETE /api/students/{id}`.
-5. In `StudentControllerTest.java`, add a test before you change the code.
+5. In `CourseController.java`, add a new secured endpoint such as `DELETE /api/courses/{id}`.
+6. In `CourseControllerIntegrationTest.java`, add a failing test before you change the code.
 
 ## Quick concept map
 
@@ -170,6 +222,13 @@ It runs on every push and pull request, sets up Java 17, and executes:
 - `for`: `totalScore`, `subjectSummary`, service mapping methods
 - `List`: subjects
 - `Map`: scores
+- Interfaces: `Notifier`, `EmailNotifier`
+- Inheritance: `Person`, `LearningStudent`
+- Generics: `Box<T>`
+- Streams: `StudentAnalytics`
 - Exceptions: `InvalidScoreException`, `StudentNotFoundException`
-- Annotations: `@LearningExample`, `@Service`, `@RestController`, `@RestControllerAdvice`
+- Annotations: `@LearningExample`, `@Service`, `@RestController`, `@RestControllerAdvice`, `@Entity`, `@Valid`
 - Dependency injection: `StudentController` gets `StudentService`, `StudentService` gets `InMemoryStudentRepository`
+- Validation: `CreateCourseRequest`
+- Persistence: `CourseEntity`, `CourseRepository`, H2
+- Security: HTTP basic auth for `/api/courses/**` with user `student` / `password`

docs/README.md

@@ -0,0 +1,23 @@
+# Learning Docs
+
+This folder explains how to use the repository as a guided Java and Spring Boot course.
+
+## Reading order
+
+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)
+
+## Main idea
+
+The repo is intentionally split into two layers:
+
+- `basics`
+  - small, plain Java examples
+- `spring`
+  - framework examples built on top of the Java basics
+
+Use the code and the tests together. In this repo, tests are part of the documentation.

docs/java-basics.md

@@ -0,0 +1,185 @@
+# Java Basics Guide
+
+This repo covers the most important beginner Java concepts through small, focused classes.
+
+## Classes and objects
+
+Main example:
+
+- `basics/model/Student.java`
+
+What to notice:
+
+- a class defines data and behavior
+- `Student student = new Student("Mia", 19);` creates an object
+- fields store state like `name`, `age`, `subjects`, and `scores`
+
+## Variables and types
+
+Examples in `Student.java`:
+
+- `long id`
+- `String name`
+- `int age`
+- `boolean active`
+- `List<String> subjects`
+- `Map<String, Integer> scores`
+
+Learn the difference between:
+
+- primitive types
+  - `int`, `long`, `boolean`
+- object/reference types
+  - `String`, `List`, `Map`, custom classes
+
+## Constructors
+
+`Student` has overloaded constructors.
+
+Why that matters:
+
+- one constructor gives a simple entry point
+- another constructor allows more detailed initialization
+
+This is common in real Java code when you want both convenience and control.
+
+## Methods
+
+Examples:
+
+- `activate()`
+- `enroll(String subject)`
+- `addScore(String subject, int score)`
+- `level()`
+- `totalScore()`
+
+Methods:
+
+- receive input through parameters
+- use object state
+- return values or change state
+
+## `if` and `for`
+
+Examples:
+
+- `if` in `enroll`, `addScore`, and `level`
+- `for` in `totalScore` and `subjectSummary`
+
+Key idea:
+
+- `if` chooses behavior
+- `for` repeats behavior
+
+## List and Map
+
+`List<String>`:
+
+- keeps ordered values
+- used here for subjects
+
+`Map<String, Integer>`:
+
+- stores key/value pairs
+- used here for scores
+
+These are core Java collection types you will use constantly.
+
+## Exceptions
+
+Example:
+
+- `InvalidScoreException`
+
+Used in:
+
+- `Student.addScore`
+
+Reason:
+
+- exceptions stop invalid behavior early
+- they make failure explicit
+
+## Packages
+
+Packages organize code by topic and responsibility.
+
+Examples:
+
+- `com.example.demo.basics.model`
+- `com.example.demo.spring.service`
+
+This is how Java projects stay readable as they grow.
+
+## Annotations
+
+Examples:
+
+- custom annotation: `@LearningExample`
+- framework annotations later in Spring: `@Service`, `@RestController`, `@Entity`
+
+Annotations add metadata to classes and methods. In Spring, annotations drive framework behavior.
+
+## Interfaces
+
+Examples:
+
+- `Notifier`
+- `EmailNotifier`
+
+Key idea:
+
+- an interface defines a contract
+- classes implement that contract
+- callers can depend on the interface instead of the concrete class
+
+This becomes very important in framework code and testable design.
+
+## Inheritance and polymorphism
+
+Examples:
+
+- `Person`
+- `LearningStudent`
+
+Key idea:
+
+- child classes reuse parent behavior
+- child classes can override methods
+- polymorphism lets you use the parent type while executing child behavior
+
+## Generics
+
+Example:
+
+- `Box<T>`
+
+Key idea:
+
+- generics let you write reusable classes while keeping type safety
+- `Box<String>` and `Box<Integer>` use the same class with different types
+
+## Streams and lambdas
+
+Example:
+
+- `StudentAnalytics`
+
+Key operations:
+
+- `stream()`
+- `filter(...)`
+- `map(...)`
+- `collect(...)`
+
+Use streams when you want to transform or summarize collections in a readable pipeline.
+
+## How to practice
+
+Good small exercises:
+
+1. Add `averageScore()` to `Student`
+2. Add a second `Notifier` implementation
+3. Add another subclass of `Person`
+4. Add a generic method to `Box`
+5. Add a new analytics method using streams