🏡 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

+-------------+
| 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

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

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:

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:

./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

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

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