84d7647481
All checks were successful
continuous-integration/drone/push Build is passing
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.
179 lines
5.5 KiB
Markdown
179 lines
5.5 KiB
Markdown
# 🏡 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
|
||
|
||
|
||
|