chore: adjust README.md

Author: Piotr Kubicki

README.md

@@ -1,25 +1,52 @@
-# Java Backend Developer Training – Lab Source
+# Java Backend Developer Training – Reference Implementation
 
-> 📌 **This repository contains the reference implementation of the application developed during the Java Backend Developer training.**\
-> Participants progressively gain access to additional branches as they progress through the course.
+> 📌 **This repository contains the _reference implementation_ of the application developed step-by-step during the _Java Backend Developer Training_.**  
+> Each subsequent branch adds more functionality on top of the previous one, allowing participants to explore and compare their solutions.
 
 ## 📖 Project Overview
 
-This project is a **Spring Boot 3** application designed to serve as a **backend development reference implementation**. It follows **clean coding principles** and modern development best practices.
+This is a **Spring Boot 3** backend application named **_Appointment Booking System_**, created as part of hands-on backend development training.  
+It follows modern architectural and coding practices, including **clean code**, **layered structure**, and **modular design**.
 
-The application developed during the Java Backend Developer training is called _**Appointment Booking System**_. 
+📄 Specification: [**AppointmentBookingAppDoc.md**](AppointmentBookingAppDoc.md)
 
-#### Here you will find the specification: **[AppointmentBookingAppDoc.md](AppointmentBookingAppDoc.md).**
+## 🌱 Branch Progression
 
-### 🛠 Tech Stack
+The repository grows in complexity and functionality across branches:
+
+| Branch | Description                                                            |
+|--------|------------------------------------------------------------------------|
+| `main` | Base Spring Boot setup with basic health and H2 endpoints              |
+| `feature/1-create-new-application` | Same as main                                                           |
+| `feature/2-dataaccess` | Persistence layer with Spring Data JPA and H2                          |
+| `feature/3-business-logic` | Service layer and business logic introduced                            |
+| `feature/4-services` | OpenAPI/Swagger setup for live API documentation and testing           |
+| `feature/5-security` | Spring Security integration for basic authentication and authorization |
+
+## 🌐 Useful Endpoints
+
+After starting the application, you can access the following in your browser:
+
+| URL | Available from | Description |
+|-----|----------------|-------------|
+| [http://localhost:8080/actuator/health](http://localhost:8080/actuator/health) | `main` | Basic application health check |
+| [http://localhost:8080/h2-console](http://localhost:8080/h2-console) | `main` | In-memory H2 database console |
+| [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) | `feature/4-services` | OpenAPI UI for testing and exploring REST API |
+
+## 🛠 Tech Stack
 
 - **Java 21**
 - **Spring Boot 3**
-- **Maven 3.9.x** as the build tool
-- **JUnit 5 & AssertJ** for testing
+- **Maven 3.9+**
+- **JUnit 5 & AssertJ**
+- **H2 Database**
+- **OpenAPI & Swagger UI**
+- **Spring Security**
 - **GitHub Actions** for CI/CD
 
-## 📂 Repository Structure
+## 📁 Project Structure
+
+
 
 ```
 java-backend-developer-app/
@@ -80,12 +107,17 @@ GitHub Actions is used for CI/CD, configured in \`.github/workflows/ci.yml\`. Th
 - **Every push and pull request** to \`main\` and feature branches.
 - **Runs tests** and generates reports.
 
+## 🙋 Who Is This For?
+This reference repo is intended for trainers and mentors to demonstrate completed solutions.
+🧑‍💻 **Each training participant works independently in a separate student repository.** This repository serves as a working example.
+
 ## 🤝 Contribution Guidelines
 
-1. Create a **feature branch** for any changes.
+1. Create a **feature branch** for any changes from a particular, possibly smallest "main" feature branch, e.g. 'feature/2-data-access'.
 2. Ensure the code **follows project conventions** and is properly tested.
-3. Open a **Pull Request** to \`main\`. Direct pushes are restricted.
+3. Open a **Pull Request** to particular, corresponding "main" feature branch, e.g. 'feature/2-data-access'. Direct pushes are restricted. 
 4. Wait for **CI to pass** and a **review** before merging.
+5. Rebase higher feature branches onto changed one, e.g. if you merged to 'feature/3-business-logic', then you should rebase 'feature/4-services' and 'feature/5-security' to have your changes there as well.
 
 ## License