diff --git a/README.md b/README.md
index 5cc86ea..d485374 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,44 @@
-# SOA
+Here’s a cleaner and more informative version of your README section:
 
-```
-docker compose up -d --build
-```
+---
 
-```
-./setup-keycloak.sh
-```
+# 🧩 SOA – Service-Oriented Architecture Project
 
-Hosts:
-```
-127.0.0.1 api.local auth.local
-```
\ No newline at end of file
+## 🚀 Quick Start
+
+1. **Start the application stack:**
+
+   ```bash
+   docker compose up -d --build
+   ```
+
+2. **Initialize Keycloak configuration:**
+
+   ```bash
+   ./setup-keycloak.sh
+   ```
+
+3. **Update your `/etc/hosts` file:**
+
+   ```
+   127.0.0.1  api.local auth.local
+   ```
+
+---
+
+## 🔐 Credentials
+
+### Keycloak Admin Panel
+
+* 📍 URL: [http://auth.local:8080](http://auth.local:8080)
+* 👤 **Username:** `admin`
+* 🔑 **Password:** `admin`
+
+### Private API User
+
+* 👤 **Username:** `alexis`
+* 🔑 **Password:** `password`
+
+---
+
+Let me know if you'd like to include API endpoints, Keycloak realm details, or `.env` config tips.