diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5628dbd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,165 @@
+# 🚀 kotlin-api
+
+![Kotlin](https://img.shields.io/badge/Kotlin-2.4.0-7F52FF?logo=kotlin&logoColor=white)
+![Spring Boot](https://img.shields.io/badge/Spring_Boot-4.1.0--RC1-6DB33F?logo=springboot&logoColor=white)
+![Java](https://img.shields.io/badge/Java-21-ED8B00?logo=openjdk&logoColor=white)
+![MongoDB](https://img.shields.io/badge/MongoDB-8.0-47A248?logo=mongodb&logoColor=white)
+![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+A reactive REST API built with **Kotlin**, **Spring Boot WebFlux**, and **MongoDB** — featuring JWT authentication, role-based access control, and OpenAPI documentation.
+
+---
+
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Tech Stack](#-tech-stack)
+- [Getting Started](#-getting-started)
+  - [Prerequisites](#prerequisites)
+  - [Configuration](#configuration)
+  - [Run Locally](#run-locally)
+  - [Run with Docker](#run-with-docker)
+- [API Reference](#-api-reference)
+- [Project Structure](#-project-structure)
+- [Development](#-development)
+
+---
+
+## ✨ Features
+
+- ⚡ **Reactive** — fully non-blocking with Spring WebFlux & Kotlin coroutines
+- 🔐 **JWT authentication** — AES-256-GCM encrypted tokens (JWE), access + refresh token flow
+- 🛡️ **Role-based access control** — `ROLE_ADMIN` and standard user roles
+- 🔄 **Token lifecycle management** — refresh, revocation, and session tracking
+- 📖 **OpenAPI / Swagger UI** — auto-generated, browsable API docs
+- 🐳 **Docker-ready** — multi-stage distroless image for minimal attack surface
+- ✅ **Code quality** — enforced with ktlint
+
+---
+
+## 🛠 Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Language | Kotlin 2.4 |
+| Framework | Spring Boot 4.1 (WebFlux) |
+| Runtime | Java 21 |
+| Database | MongoDB 8 (reactive) |
+| Security | Spring Security + JJWT (JWE) |
+| Docs | SpringDoc OpenAPI 3 |
+| Testing | JUnit 5, MockK, embedded MongoDB |
+| Linting | ktlint 1.8 |
+
+---
+
+## 🏁 Getting Started
+
+### Prerequisites
+
+- Java 21+
+- MongoDB 8 (or Docker)
+
+### Configuration
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set the required values:
+
+| Variable | Description | Default |
+|---|---|---|
+| `MONGODB_URI` | MongoDB connection string | `mongodb://localhost:27017/kotlin-api` |
+| `JWT_ENCRYPTION_SECRET` | Base64-encoded 32-byte AES secret (**required**) | — |
+
+Generate a secret:
+```bash
+openssl rand -base64 32 | tr -d '\n'
+```
+
+### Run Locally
+
+```bash
+./gradlew bootRun
+```
+
+The API starts on **http://localhost:8080**.
+
+### Run with Docker
+
+```bash
+docker compose up --build
+```
+
+This spins up both the API and MongoDB with a persistent volume.
+
+---
+
+## 📡 API Reference
+
+All routes are versioned under `/v1`. Interactive docs available at **http://localhost:8080/swagger-ui.html**.
+
+### 🔓 Auth
+
+| Method | Endpoint | Auth | Description |
+|---|---|---|---|
+| `POST` | `/v1/auth/login` | — | Login, returns access + refresh tokens |
+| `POST` | `/v1/auth/refresh` | — | Exchange refresh token for a new access token |
+| `POST` | `/v1/auth/logout` | Bearer | Revoke all refresh tokens for the current user |
+
+### 👤 Users
+
+| Method | Endpoint | Auth | Description |
+|---|---|---|---|
+| `GET` | `/v1/users/me` | Bearer | Get current user info and active sessions |
+| `GET` | `/v1/users` | Admin | List all users |
+
+### 🔧 Admin
+
+| Method | Endpoint | Auth | Description |
+|---|---|---|---|
+| `POST` | `/v1/admin/users` | Admin | Create a new user |
+
+### 💚 Health
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/v1/health` | API and MongoDB health status |
+
+---
+
+## 📁 Project Structure
+
+```
+src/main/kotlin/io/visus/demos/kotlinapi/
+├── api/                  # Contracts (request/response DTOs), mappers, versioning
+├── config/               # Spring configuration (security, JWT, OpenAPI, MongoDB)
+├── controller/           # HTTP layer (Auth, Admin, Users, Health)
+├── domain/
+│   ├── model/            # Domain models
+│   ├── service/          # Business logic interfaces + implementations
+│   └── exception/        # Custom exceptions + global error handler
+├── infrastructure/
+│   ├── security/         # JWT filter, token provider, auth handlers
+│   └── user/             # Repository interfaces (MongoDB)
+└── seed/                 # Data seeder (dev only)
+```
+
+---
+
+## 🧑‍💻 Development
+
+```bash
+# Run tests
+./gradlew test
+
+# Lint
+./gradlew ktlintCheck
+
+# Auto-fix lint issues
+./gradlew ktlintFormat
+
+# Check for dependency updates
+./gradlew dependencyUpdates
+```