🤖 RoomMate AI Copilot

RoomMate ist ein Spring-Boot-Projekt für die Raum- und Platzbuchung mit einem klaren Schwerpunkt auf einem AI Copilot, der Buchungen per Chat versteht, freie Plätze findet und Buchungen über Tool-Calls ausführt.

Statt durch klassische Formulare zu klicken, können Nutzer in natürlicher Sprache fragen:

• „Zeig mir morgen freie GPU-Plätze.“
• „Buche mir in Raum 3 Platz 3 um 12 Uhr, wenn er frei ist.“
• „Welche Buchungen habe ich morgen?“

Der Copilot übersetzt diese Anfragen in strukturierte Tool-Aufrufe und greift dabei auf die bestehenden Fachlogiken für Räume, Plätze und Zeitslots zurück.

---

✨ Fokus des Projekts

Der Kern dieses Projekts ist nicht nur eine klassische Buchungsanwendung, sondern vor allem die Verbindung aus:

• Spring Boot als stabile Backend-Basis
• Spring AI für den Chat-basierten Copilot
• Tool Calling für deterministische Fachlogik
• Spring Security + OAuth2 für authentifizierte Nutzerinteraktion
• PostgreSQL + Flyway für persistente, versionierte Datenhaltung

Das Ziel ist ein Assistenzsystem, das natürliche Sprache mit verlässlicher Buchungslogik kombiniert.

---

🧠 Was der AI Copilot kann

Der KI-Assistent unterstützt aktuell unter anderem folgende Aufgaben:

• verfügbare Räume auflisten
• Plätze nach Ausstattung suchen, zum Beispiel GPU, Monitor oder MacBook
• freie Zeitslots für einen Platz finden
• eigene Buchungen anzeigen
• konkrete Buchungswünsche per Tool-Aufruf prüfen und ausführen

Wichtig dabei: Die kritischen Entscheidungen wie Raum-/Platzauflösung, Slot-Prüfung und Buchung werden nicht dem LLM überlassen, sondern im Backend durch dedizierte Tool-Methoden ausgeführt. Dadurch wird Halluzination reduziert und die Buchung robuster.

---

💬 Beispiel-Screenshots des AI Chats

Beispiel 1 – KI-Copilot im Chat

Beispiel 2 – Buchungsdialog im Chat

---

🏗️ Architektur

Das Projekt ist in mehrere Verantwortungsbereiche getrennt:

• web: Controller, DTOs, Formulare
• ai: AI Chat Service und Tool-Klassen
• service: Fachlogik für Räume, Plätze und Zeitslots
• domain: Modelle und Repository-Abstraktionen
• db: Datenbankanbindung und Persistenz
• configuration: Security und App-Konfiguration

AI-spezifische Struktur

Die KI-Funktionalität ist bewusst getrennt aufgebaut:

• AIChatController: HTTP-Einstiegspunkt für /api/chat
• AiChatService: kapselt den ChatClient, Prompt, Tool-Namen und Chat-Memory
• RoomTools: Tools rund um Räume und Plätze pro Raum
• PlatzTools: Tools für Ausstattungssuche und freie Zeitslots
• BookingTools: Tools für Buchung, eigene Buchungen und deterministische Slot-Prüfung

Diese Trennung macht die KI-Logik deutlich besser testbar und wartbarer.

---

🔧 Tool-Calling statt reiner Text-Antworten

Ein zentrales Designziel des Projekts ist, dass der AI Copilot nicht frei raten soll, wenn eine Buchung fachlich geprüft werden muss.

Deshalb nutzt RoomMate Tool-Calling, zum Beispiel für:

• holeAlleRaeumeTool
• suchePlaetzeNachAusstattungTool
• holeFreieZeitslotsFuerPlatzTool
• holeMeineBuchungenTool
• bucheZeitslotTool
• pruefeUndBucheSlotTool

Gerade pruefeUndBucheSlotTool ist wichtig, weil dadurch der Copilot nicht selbst Platz-IDs oder Verfügbarkeiten erraten muss. Die Entscheidung, ob ein Slot existiert, frei ist und gebucht werden kann, trifft das Backend deterministisch.

---

🛠️ Tech Stack

• Backend: Java 21, Spring Boot 3.5.x
• AI: Spring AI 1.1.x, OpenAI Chat Model (gpt-5.4-mini)
• Security: Spring Security, OAuth2 Login mit GitHub
• Frontend: Thymeleaf, Bootstrap
• Datenbank: PostgreSQL
• Migration: Flyway
• Build: Gradle
• Tests: JUnit 5, Mockito, Spring Boot Test, WebMvcTest
• Container: Docker / Docker Compose

---

🚀 Lokales Setup

1. Datenbank starten

Am einfachsten startest du PostgreSQL über Docker:

docker-compose up -d

Danach läuft die Datenbank lokal auf Port 5433.

---

2. Umgebungsvariablen setzen

Vor dem Start der Anwendung müssen Umgebungsvariablen gesetzt werden.

DB_USER=dein_postgres_benutzername
DB_PASSWORD=dein_postgres_passwort
CLIENT_ID=deine_github_oauth_client_id
CLIENT_SECRET=deine_github_oauth_client_secret
OPENAI_API_KEY=dein_openai_api_key

---

3. Anwendung starten

Windows

gradlew bootRun

macOS / Linux

./gradlew bootRun

Danach ist die Anwendung unter http://localhost:8080 erreichbar.

---

🔐 Login & Sicherheit

RoomMate verwendet GitHub OAuth2 für den Login. Dadurch ist der Chat nicht anonym, sondern kann mit dem aktuell eingeloggten Nutzer arbeiten.

Das ist wichtig für AI-Features wie:

• „Welche Buchungen habe ich?“
• „Buche den Slot für mich.“

Zusätzlich schützt Spring Security die Anwendung, und CSRF-Schutz ist für relevante Requests aktiv.

---

✅ Tests

Das Projekt enthält Unit- und Web-Tests für die KI- und Web-Schichten.

Getestet werden unter anderem:

• AIChatController
• AiChatService
• RoomTools
• PlatzTools
• BookingTools

Tests starten:

./gradlew test

---

📌 Beispiel-Use-Cases

Typische Chat-Anfragen in RoomMate sind:

• „Zeig mir freie GPU-Plätze.“
• „Welche Plätze gibt es in Raum 3?“
• „Welche freien Zeitslots gibt es für Platz 10?“
• „Buche mir Raum 3 Platz 2 am 2026-03-26 um 12:00.“
• „Welche Buchungen habe ich aktuell?“

---

🎯 Projektziel

RoomMate demonstriert, wie sich ein klassisches Spring-Boot-System mit einem AI Copilot erweitern lässt, ohne kritische Geschäftslogik dem Modell allein zu überlassen.

Der Fokus liegt auf einer praxisnahen Kombination aus:

• natürlicher Sprache im Frontend
• strukturierten Tool-Aufrufen im Backend
• klarer Rollen- und Sicherheitslogik
• testbarer, wartbarer Architektur