From d8f91f42e598310f07c215e15b89bc74cd071c8c Mon Sep 17 00:00:00 2001
From: oskar <oskar@kapalla.org>
Date: Mon, 12 Jan 2026 22:50:15 +0100
Subject: [PATCH] Improved `README.md` with restructured sections, better
 formatting, and added examples for local development, testing, and
 architecture overview.

---
 back001/README.md | 86 +++++++++++++++++++++++------------------------
 1 file changed, 43 insertions(+), 43 deletions(-)

diff --git a/back001/README.md b/back001/README.md
index bb3d593..6352708 100644
--- a/back001/README.md
+++ b/back001/README.md
@@ -2,65 +2,65 @@
 
 Production-ready Kotlin/Spring Boot 3 modular monolith skeleton for patient-caregiver-doctor coordination.
 
-## Requirements
+## 🏛 Architecture
+This project follows a **Modular Monolith** architecture:
+- `app`: Main entry point, configuration, and shared controllers.
+- `common`: Cross-cutting concerns (security, tenant handling, outbox pattern).
+- `modules/*`: Independent business modules (Clinical, Identity, Messaging, etc.).
+- `workers/*`: Background event consumers/processors.
+
+## 🛠 Requirements
 - Java 21
 - Docker + Docker Compose
 
-## Local run
-1) Start dependencies:
+## 🚀 Local Run
 
+### 1. Start Dependencies
 ```bash
 docker compose up -d
 ```
 
-2) Run the API (local profile, local auth enabled):
+### 2. Run the API
+Choose a profile:
 
+**Local Development (with mock auth):**
 ```bash
-SPRING_PROFILES_ACTIVE=local \
-ALLOW_LOCAL_AUTH=true \
-./gradlew :app:bootRun
+SPRING_PROFILES_ACTIVE=local ALLOW_LOCAL_AUTH=true ./gradlew :app:bootRun
+```
+*Allows bypassing Keycloak using `X-Local-*` headers.*
+
+**Dev Mode (with Keycloak):**
+```bash
+SPRING_PROFILES_ACTIVE=dev ./gradlew :app:bootRun
 ```
 
-```bash
-SPRING_PROFILES_ACTIVE=dev \
-ALLOW_LOCAL_AUTH=false \
-./gradlew :app:bootRun
-```
-
-3) (Optional) Run the worker:
-
+### 3. Run the Worker (Optional)
 ```bash
 ./gradlew :workers:notification-worker:bootRun
 ```
 
-Required env flags (local/dev):
-- `SPRING_PROFILES_ACTIVE=local`
-- `ALLOW_LOCAL_AUTH=true` (enables local auth headers)
-- `KEYCLOAK_ISSUER_URI=http://localhost:8081/realms/mosenioring` (if using Keycloak)
-- Frontend should set `USE_LOCAL_AUTH=true` when using local auth headers.
+## 🧪 Testing
+Run all tests:
+```bash
+./gradlew test
+```
 
-## Auth
-- The backend is a JWT resource server and does not handle user passwords.
-- Local auth shortcut is available only when `SPRING_PROFILES_ACTIVE=local`
-  and `ALLOW_LOCAL_AUTH=true`.
+## 🔐 Auth & Multi-tenancy
+- **JWT Resource Server**: Uses Keycloak by default.
+- **Multi-tenancy**: Enforced via `X-Tenant-Id` header (local) or `tenant_id` JWT claim.
+- **Local Auth Headers** (only when `ALLOW_LOCAL_AUTH=true`):
+  - `X-Local-Email`: User identity.
+  - `X-Local-Roles`: e.g., `ADMIN, DOCTOR, CAREGIVER`.
+  - `X-Tenant-Id`: Target tenant.
 
-Local headers (dev only):
-- `X-Local-Email`: user id/email
-- `X-Local-Roles`: comma-separated roles (ADMIN, DOCTOR, CAREGIVER)
-- `X-Tenant-Id`: tenant id
+## 🔗 Key Services & Links
+- **OpenAPI**: [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html)
+- **Health**: [http://localhost:8080/health](http://localhost:8080/health)
+- **Postgres**: `localhost:5432` (mosenioring/mosenioring)
+- **Keycloak**: [http://localhost:8081](http://localhost:8081) (admin/admin)
+- **RabbitMQ**: [http://localhost:15672](http://localhost:15672) (guest/guest)
+- **MinIO**: [http://localhost:9001](http://localhost:9001) (minio/minio123)
 
-## OpenAPI
-- http://localhost:8080/swagger-ui/index.html
-## Health
-- http://localhost:8080/health
-
-## Key services
-- Postgres: localhost:5432 (mosenioring/mosenioring)
-- Keycloak: http://localhost:8081 (admin/admin)
-- RabbitMQ: http://localhost:15672 (guest/guest)
-- MinIO: http://localhost:9001 (minio/minio123)
-
-## Notes
-- Tenant ID is enforced via `TenantFilter` using JWT claim `tenant_id`, or `X-Tenant-Id` header (local).
-- Medication plan creation publishes a `MedicationPlanCreated` outbox event.
-- Worker consumes and emits `NotificationRequested` events with idempotency via Redis.
+## 📝 Notes
+- **Outbox Pattern**: Medication plans publish events to an outbox table for reliable messaging.
+- **Idempotency**: Workers use Redis to ensure events are processed only once.