Feat/update readme (#101)

* update readme

* update readme

* update readme

* update readme

* update readme

* update readme

* update readme

* update readme

* update readme

Author: vmillet-dev

README.md

@@ -1,30 +1,61 @@
 # ✈️ Tripr
 
-> **fast SaaS Starter** combining the power of **Spring Boot 3 (Kotlin)** and the reactivity of **Angular 21 (Signals)**.
+> **Modern SaaS Starter** combining the power of **Spring Boot 4 (Kotlin)** and the reactivity of **Angular 21 (Signals)**.
 
 [![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/example/tripr/actions)
 [![Kotlin](https://img.shields.io/badge/Kotlin-2.3.10-blue.svg)](https://kotlinlang.org/)
 [![Angular](https://img.shields.io/badge/Angular-21-red.svg)](https://angular.dev/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-Tripr is a production-ready template designed for scalability, security, and a smooth developer experience. It integrates a strict hexagonal architecture on the backend and a reactive zoneless approach on the frontend.
+Tripr is a production-ready template designed for scalability, security, and a smooth developer experience. It features a **contract-first approach** using OpenAPI to bridge the gap between a strict Hexagonal backend and a reactive Zoneless frontend.
 
 ### 🏗️ Architecture Overview
 
 ```mermaid
 graph LR
-    User((User)) <--> Front[Angular App <br/><i>Signals & Zoneless</i>]
-    Front <--> Back[Spring Boot API <br/><i>Hexagonal Architecture</i>]
-    Back <--> DB[(PostgreSQL)]
-    Back <--> SMTP[SMTP Service]
+
+  subgraph Angular
+    A1[Components]
+    A2[Services]
+  end
+
+  subgraph OpenAPI-Generator
+    O1[openapi.yaml]
+    O2[TS Client]
+  end
+
+  subgraph Spring-Boot
+    subgraph adapters-in
+      B1[REST Controllers]
+    end
+    subgraph domain
+      B2[Ports In]
+      B3[Services / Use Cases]
+      B4[Ports Out]
+    end
+    subgraph adapters-out
+      B5[Persistence JPA]
+      B6[Notification Email]
+    end
+    subgraph application
+      B7[Main / Config]
+    end
+
+    B1 --> B2 --> B3 --> B4
+    B4 --> B5
+    B4 --> B6
+  end
+
+  A2 --> O1 --> O2 --> B1
 ```
 
 ### 🛠️ Tech Stack
 
 | Component    | Key Technologies                                                                     |
 |:-------------|:-------------------------------------------------------------------------------------|
 | **Backend**  | Kotlin, Spring Boot 4.+, Spring Security (JWT), Liquibase, MapStruct, Testcontainers |
-| **Frontend** | Angular 21, Vite, Vitest, Bootstrap 5, Transloco (i18n), Signals                     |
+| **Frontend** | Angular 21, Vite, Vitest, Bootstrap 5, Transloco (i18n), Signals, Zoneless           |
+| **Bridge**   | **OpenAPI Generator** (Automatic Model & API Synchronization)                        |
 | **DevOps**   | Docker, GitHub Actions, Ansible                                                      |
 
 ---
@@ -63,4 +94,4 @@ cd frontend && npm install && npm run dev
 ---
 
 - 📖 [**Backend Documentation**](backend/README.md) — *Architecture, API & Tests*
-- 📖 [**Frontend Documentation**](frontend/README.md) — *Signals, Standalone & Vite*
+- 📖 [**Frontend Documentation**](frontend/README.md) — *Modern Angular, Tooling & Vite*

backend/README.md

@@ -1,6 +1,8 @@
 # 🏗️ Tripr API — Backend
 
-Robust API built with **Spring Boot 3.4** and **Kotlin**, using a strict **Hexagonal Architecture** to ensure domain isolation and testability.
+Robust API built with **Spring Boot 4** and **Kotlin**, using a strict **Hexagonal Architecture** to ensure domain isolation and testability.
+
+The project follows a **Contract-First** approach using **OpenAPI**. The server-side code is generated from the OpenAPI spec, ensuring a perfect sync between documentation and implementation.
 
 🔗 **Swagger UI** (dev mode): [http://localhost:8080/api/swagger-ui](http://localhost:8080/api/swagger-ui)
 
@@ -13,14 +15,14 @@ The project follows the **Ports & Adapters** pattern to decouple business logic
 - **`domain/`**: **The Core**.
     - `model/`: Domain entities and value objects.
     - `port/`: Inbound (In) and Outbound (Out) interfaces.
-    - `service/`: Business orchestration implementing *In-Ports* by using *Out-Ports*.
+    - `service/`: Business orchestration. Services implement *In-Ports* and use *Out-Ports* to execute business logic.
 - **`infrastructure/`**: **The Adapters**.
-    - Concrete port implementations (JPA/PostgreSQL Persistence, JWT Security, SMTP Email).
-    - REST Controllers and external configurations.
+    - Concrete implementations of *Out-Ports* (Persistence with JPA/PostgreSQL, Security with JWT, Email with SMTP).
+    - Inbound adapters such as REST Controllers.
 - **`application/`**: **The Shell**.
-    - Application bootstrap (Main class).
-    - Global configuration (Spring, Security, Liquibase).
-    - Integration tests and architectural compliance (**ArchUnit**).
+    - Entry point of the application (Main class).
+    - Global configurations (Spring, Security, Docker Compose).
+    - Integration tests and architectural validation (**ArchUnit**).
 
 ---
 

frontend/README.md

@@ -6,13 +6,13 @@ Modern **Angular 21** application, optimized for performance and developer exper
 
 ### 🎨 Principles & Conventions
 
-This project embraces the latest innovations in the Angular ecosystem:
+This project follows modern Angular standards to ensure maintainability and performance:
 
-- **Signals**: Reactive and granular state management.
-- **Zoneless**: Removal of `zone.js` for increased performance and better control over the rendering cycle.
-- **Standalone Components**: Modular architecture without `NgModules`.
-- **Vite & Analog**: Ultra-fast tooling for development and build.
-- **Internationalization**: Multi-language support via **Transloco**.
+- **Standalone Components**: Modular architecture without the overhead of `NgModules`.
+- **Reactive State**: Strategic use of **Signals** and **RxJS** for clean data flow.
+- **Performance**: Optimization with **Zoneless** change detection.
+- **Tooling**: Ultra-fast development and builds via **Vite** and **Analog**.
+- **I18n**: Full internationalization support with **Transloco**.
 
 ---