mohamed-taman/hotel-booking-ai-assistant

1. Overall shape

- This is a single Spring Boot application with a full-stack UI. The backend owns all business logic, persistence, AI orchestration, and endpoint exposure; the frontend is a Vaadin/Hilla React client bundled into the same deployable artifact.

2. Request entry points

- End users interact through the browser UI in src/main/frontend, which is built with React, TypeScript, and Vite.

- The UI talks to backend “UI services” under rs.siriusxi.hbca.ui, rather than calling repositories or AI code directly.

3. UI boundary

- AssistantUIService handles the chat conversation path.

- HotelBookingUIService exposes booking-related data to the UI.

- src/main/resources/META-INF/resources provides static assets such as global styling, while the React view files define the interactive chat screen.

4. Conversation / AI subsystem

- CustomerSupportAssistant is the AI-facing orchestration layer.

- It uses Spring AI to send user messages to an OpenAI chat model, maintain conversation context, and stream responses back to the UI.

- This layer is the main boundary between natural-language input and executable hotel operations.

5. Tool calling and business actions

- BookingToolsConfig wires “tools” that the model can invoke for real actions such as lookup, modification, or cancellation.

- This creates a controlled path from LLM intent → tool invocation → domain service execution, rather than letting the model access data directly.

6. Core business service

- HotelBookingService is the central domain service for booking operations.

- It enforces the booking rules and delegates to repositories for persistence.

- BookingDetailsMapper translates domain entities into UI-friendly DTOs, keeping the UI insulated from persistence details.

7. Persistence model

- The domain is intentionally small: Booking, Customer, BookingStatus, and RoomType.

- Data access is through Spring Data repositories: BookingRepository and CustomerRepository.

- The app uses a file-backed H2 database, with schema and seed data managed by Flyway migrations in src/main/resources/db/migration.

8. Knowledge / RAG layer

- Hotel policy text lives in booking-terms.txt.

- The app uses a file-backed vector store for retrieval-augmented generation so the assistant can answer policy questions and validate booking changes against the terms.

- SystemMessage.st holds the system prompt template that shapes assistant behavior.

9. Startup and wiring

- HCSAApplication is the Spring Boot entry point and is also where the vector-store initialization is tied into application startup.

- Configuration classes under config/ assemble the application context: general app wiring, AI tools, security, OpenTelemetry/logging, and context propagation.

10. Cross-cutting concerns

- SecurityConfig defines the request security boundary.

- TraceIdFilter, ContextPropagationConfiguration, and OpenTelemetryAppenderInstaller show that observability is a first-class concern: trace IDs are propagated into logs and telemetry can be exported via OpenTelemetry/OTLP.

- logback-spring.xml and application.yaml complete the runtime logging/telemetry setup.

11. Build and runtime topology

- The project is built with Maven, but it also has a Node/Vite toolchain for the frontend.

- Docker support packages the whole stack into one container; compose.yaml is present for optional local infrastructure.

- Tests are minimal in the repo snapshot, centered around application startup verification.

12. External dependencies that matter architecturally

- OpenAI is the main external AI service.

- A local OTLP-compatible backend can receive traces/metrics/logs if configured.

- No separate microservices are visible; the architecture is a modular monolith with clear internal layers: UI → AI orchestration → domain services → repositories → H2/Flyway, plus a side path to the vector store for policy retrieval.