# 🏡 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