Add household and membership domain with role-based APIs

Introduced `Household` and `HouseholdMember` entities, services, and repositories, enabling role-based access (`OWNER` and `MEMBER`). Added REST APIs for household creation, member management, and listing. Configured Flyway migrations, updated tests, and included IntelliJ HTTP client script for API testing. Updated `README.md` with feature details, usage instructions, and architecture overview.

Readme.md

@@ -0,0 +1,178 @@
+# 🏡 HemHub – A Home & Household Management API
+
+HemHub is a Spring Boot 3 application showcasing secure, role-based APIs using **Spring Security**, **OAuth2 JWT**, and **Keycloak**.  
+The system models households, members, and tasks (future iterations), providing a realistic multi-tenant backend suitable for professional portfolio or consulting demonstrations.
+
+---
+
+## ✨ Features
+
+### Iteration 1 – Security Foundation
+- OAuth2 / JWT authentication via **Keycloak 25**.
+- `/me` endpoint exposing user claims and roles.
+- Dockerized Keycloak + API stack.
+- Unit and integration tests for security validation.
+
+### Iteration 2 – Household & Membership Domain
+- PostgreSQL persistence with **Flyway** migrations.
+- Entities: `Household`, `HouseholdMember`.
+- Role-based access (`OWNER` / `MEMBER`).
+- Guarded endpoints with method-level security.
+- Integration tests for domain logic and security.
+- IntelliJ HTTP Client script for easy manual testing.
+
+---
+
+## 🧱 Architecture Overview
+```bash
++-------------+
+| Keycloak    | <-- OAuth2 provider (JWT tokens)
++-------------+
+       |
+       v
++-------------------+     +-------------------------+
+| hemhub-api        | --> | PostgreSQL 16 database |
+| Spring Boot app   |     +-------------------------+
+| ├─ SecurityConfig |
+| ├─ Controllers    |
+| ├─ Services       |
+| └─ JPA Entities   |
++-------------------+
+```
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Docker / Docker Compose
+- JDK 21+
+- Gradle 8+
+
+### Run
+```bash
+make run        # build + start API + Keycloak + Postgres
+```
+After startup:
+* API available at http://localhost:8080
+* Keycloak Admin Console: http://localhost:8081
+  * Username: admin
+  * Password: admin
+
+### Obtain Token
+```bash
+curl -s -X POST \
+  -d "client_id=hemhub-public" \
+  -d "grant_type=password" \
+  -d "username=maria" \
+  -d "password=Passw0rd" \
+  http://localhost:8081/realms/hemhub/protocol/openid-connect/token \
+  | jq -r .access_token
+```
+---
+## 🧪 Example API Usage
+
+### Use the included IntelliJ HTTP Client script:
+```bash
+src/test/http/hemhub-api.http
+```
+This file automates:
+1. Fetching an access token.
+2. Creating a household.
+3. Listing households and members.
+4. Adding new members.
+
+Each request stores variables (`{{token}}`, `{{householdId}}`) automatically for later steps.
+
+---
+
+## 🧰 API Endpoints
+
+| Method |                            Path | Description | Auth          |
+|--------|-----|------------|---------------|
+| GET    | /me | Current user info from JWT | 🔒Authenticated |
+| POST   | /api/v1/households | Create a new household | 🔒Authenticated |
+| GET    | /api/v1/households | List caller’s households | 🔒Authenticated |
+| GET    | /api/v1/households/{id}/members | List members in household | 🔒Member only |
+| POST   | /api/v1/households/{id}/members | Add new member | 🔒OWNER only  |
+
+---
+
+## 🧪 Testing
+Run full test suite:
+```bash
+./gradlew clean test
+```
+
+* Uses in-memory H2 database.
+* Applies Flyway migrations automatically.
+* Covers controllers, services, and access control.
+* All tests must pass before CI build succeeds.
+
+Integration tests cover endpoints, security, and service logic.
+
+## 🐳 Docker Services
+| Service      | Port | Description              |
+| ------------ | ---- | ------------------------ |
+| `hemhub-api` | 8080 | Spring Boot REST API     |
+| `keycloak`   | 8081 | OAuth2 Identity Provider |
+| `postgres`   | 5432 | PostgreSQL 16 database   |
+
+### Common commands
+```bash
+make run          # Build + start stack
+make stop         # Stop and remove containers
+make logs         # Tail logs from all services
+make image        # Build Docker image for API
+```
+---
+## ⚙️ Configuration Overview
+| Component                   | Tool                                   | Version |
+| --------------------------- | -------------------------------------- | ------- |
+| **Language**                | Java                                   | 21      |
+| **Framework**               | Spring Boot                            | 3.3.x   |
+| **Security**                | Spring Security OAuth2 Resource Server |         |
+| **Database**                | PostgreSQL                             | 16.10   |
+| **Migrations**              | Flyway                                 | 10.17.3 |
+| **Container Orchestration** | Docker Compose                         |         |
+| **Build System**            | Gradle                                 | 8.x     |
+| **Identity Provider**       | Keycloak                               | 25.x    |
+| **Testing**                 | JUnit 5, MockMvc                       |         |
+
+## 🧩 Folder Structure
+```bash
+hemhub/
+├─ src/
+│  ├─ main/java/se/urmo/hemhub/
+│  │  ├─ controller/        # REST endpoints
+│  │  ├─ domain/            # JPA entities
+│  │  ├─ repo/              # Repositories
+│  │  ├─ service/           # Business logic
+│  │  ├─ security/          # Security config & guards
+│  │  └─ HemhubApplication  # Main entry point
+│  └─ resources/
+│     ├─ db/migration/      # Flyway migrations (V1, V2, …)
+│     └─ application.yml
+│
+├─ src/test/
+│  ├─ java/…                # Unit & integration tests
+│  └─ http/hemhub-api.http  # IntelliJ HTTP test file
+│
+├─ docker-compose.yml
+├─ Makefile
+├─ build.gradle
+└─ README.md
+```
+---
+## 🧰 Development Notes
+
+* IDE: IntelliJ IDEA recommended.
+* Run IntelliJ HTTP scripts directly (src/test/http/hemhub-api.http).
+* For local debugging, set env SPRING_PROFILES_ACTIVE=dev.
+
+---
+
+## 📄 License
+
+
+