# mohamed-taman/hotel-booking-ai-assistant architecture

> Architecture diagram of the GitHub repository mohamed-taman/hotel-booking-ai-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohamed-taman/hotel-booking-ai-assistant
- Repository: https://github.com/mohamed-taman/hotel-booking-ai-assistant

## Overview

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.

Main entry points: [`src/main/java/rs/siriusxi/hbca/service/ai/CustomerSupportAssistant.java`](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/service/ai/CustomerSupportAssistant.java) (Support Assistant), [`src/main/java/rs/siriusxi/hbca/service/HotelBookingService.java`](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/service/HotelBookingService.java) (Booking Service), [`src/main/frontend`](https://github.com/mohamed-taman/hotel-booking-ai-assistant/tree/main/src/main/frontend) (React UI), [`src/main/java/rs/siriusxi/hbca/ui/AssistantUIService.java`](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/ui/AssistantUIService.java) (Assistant API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_frontend["Frontend UI"]
  node_n_frontend_react["React UI<br/>Vite React client"]
  node_n_frontend_views["Chat View<br/>Vaadin/Hilla view<br/>[@index.tsx]"]
  node_n_frontend_components["Message UI<br/>React components<br/>[Message.tsx]"]
  node_n_frontend_assets["Static Assets<br/>web assets<br/>[styles.css]"]
  node_n_ui_assistant["Assistant API<br/>UI service"]
  node_n_ui_booking["Booking API<br/>UI service"]
end

subgraph group_grp_ai["AI Orchestration"]
  node_n_ai_assistant["Support Assistant<br/>AI orchestration"]
  node_n_ai_tools["Tool Wiring<br/>tool config"]
  node_n_ai_prompt["System Prompt<br/>prompt template<br/>[SystemMessage.st]"]
  node_n_ai_terms["Policy Text<br/>knowledge source<br/>[booking-terms.txt]"]
end

subgraph group_grp_domain["Domain Model"]
  node_n_domain_service["Booking Service<br/>domain service"]
  node_n_domain_mapper["Details Mapper"]
  node_n_domain_booking[("Booking<br/>entity<br/>[Booking.java]")]
  node_n_domain_customer[("Customer<br/>entity<br/>[Customer.java]")]
  node_n_domain_repos["Repositories<br/>Spring Data"]
end

subgraph group_grp_platform["Platform"]
  node_n_platform_app["App Bootstrap<br/>Spring Boot entrypoint"]
  node_n_platform_config["App Config<br/>configuration<br/>[AppConfig.java]"]
  node_n_platform_security["Security"]
  node_n_platform_obs["Observability<br/>telemetry config"]
  node_n_platform_data["Data Layer<br/>persistence setup"]
end

node_n_frontend_react -->|"renders"| node_n_frontend_views
node_n_frontend_views -->|"uses"| node_n_frontend_components
node_n_frontend_react -->|"calls"| node_n_ui_assistant
node_n_frontend_react -->|"calls"| node_n_ui_booking
node_n_frontend_assets -.->|"styles"| node_n_frontend_react
node_n_ui_assistant -->|"delegates"| node_n_ai_assistant
node_n_ai_assistant -->|"invokes"| node_n_ai_tools
node_n_ai_assistant -->|"shaped by"| node_n_ai_prompt
node_n_ai_assistant -->|"retrieves"| node_n_ai_terms
node_n_ai_tools -->|"executes"| node_n_domain_service
node_n_ui_booking -->|"formats"| node_n_domain_mapper
node_n_domain_service -->|"persists via"| node_n_domain_repos
node_n_domain_service -->|"manages"| node_n_domain_booking
node_n_domain_service -->|"reads/writes"| node_n_domain_customer
node_n_domain_mapper -->|"maps"| node_n_domain_booking
node_n_platform_app -->|"starts with"| node_n_platform_config
node_n_platform_app -->|"initializes"| node_n_platform_data
node_n_platform_config -->|"includes"| node_n_platform_security
node_n_platform_config -->|"includes"| node_n_platform_obs
node_n_platform_obs -.->|"exports"| node_n_platform_data
node_n_ui_assistant -.->|"protected by"| node_n_platform_security
node_n_ui_booking -.->|"protected by"| node_n_platform_security

click node_n_frontend_react "https://github.com/mohamed-taman/hotel-booking-ai-assistant/tree/main/src/main/frontend"
click node_n_frontend_views "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/frontend/views/@index.tsx"
click node_n_frontend_components "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/frontend/components/Message.tsx"
click node_n_frontend_assets "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/resources/META-INF/resources/styles.css"
click node_n_ui_assistant "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/ui/AssistantUIService.java"
click node_n_ui_booking "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/ui/HotelBookingUIService.java"
click node_n_ai_assistant "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/service/ai/CustomerSupportAssistant.java"
click node_n_ai_tools "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/config/BookingToolsConfig.java"
click node_n_ai_prompt "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/resources/SystemMessage.st"
click node_n_ai_terms "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/resources/booking-terms.txt"
click node_n_domain_service "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/service/HotelBookingService.java"
click node_n_domain_mapper "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/service/mapper/BookingDetailsMapper.java"
click node_n_domain_booking "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/domain/Booking.java"
click node_n_domain_customer "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/domain/Customer.java"
click node_n_domain_repos "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/repository/BookingRepository.java"
click node_n_platform_app "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/HCSAApplication.java"
click node_n_platform_config "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/config/AppConfig.java"
click node_n_platform_security "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/config/SecurityConfig.java"
click node_n_platform_obs "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/config/ContextPropagationConfiguration.java"
click node_n_platform_data "https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/resources/db/migration/V1__Create_schema.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_frontend_react,node_n_frontend_views,node_n_frontend_components,node_n_frontend_assets,node_n_ui_assistant,node_n_ui_booking toneBlue
class node_n_ai_assistant,node_n_ai_tools,node_n_ai_prompt,node_n_ai_terms toneAmber
class node_n_domain_service,node_n_domain_mapper,node_n_domain_booking,node_n_domain_customer,node_n_domain_repos toneMint
class node_n_platform_app,node_n_platform_config,node_n_platform_security,node_n_platform_obs,node_n_platform_data toneRose
```

## Components

### Frontend UI

Browser client and UI-facing services.

- [React UI](https://github.com/mohamed-taman/hotel-booking-ai-assistant/tree/main/src/main/frontend): Vite React client · Interactive browser app built with React, TypeScript, and Vite. · `src/main/frontend`
- [Chat View](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/frontend/views/@index.tsx): Vaadin/Hilla view · Main interactive chat screen and view entry files. · `src/main/frontend/views/@index.tsx`
- [Message UI](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/frontend/components/Message.tsx): React components · Message rendering and conversation list components. · `src/main/frontend/components/Message.tsx`
- [Static Assets](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/resources/META-INF/resources/styles.css): web assets · Global styles and other served static resources. · `src/main/resources/META-INF/resources/styles.css`
- [Assistant API](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/ui/AssistantUIService.java): UI service · UI boundary for chat conversation requests and streaming responses. · `src/main/java/rs/siriusxi/hbca/ui/AssistantUIService.java`
- [Booking API](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/ui/HotelBookingUIService.java): UI service · UI-facing service for booking data and detail retrieval. · `src/main/java/rs/siriusxi/hbca/ui/HotelBookingUIService.java`

### AI Orchestration

Conversation handling, tool calling, and prompt/knowledge integration.

- [Support Assistant](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/service/ai/CustomerSupportAssistant.java): AI orchestration · Coordinates model calls, context, and response streaming. · `src/main/java/rs/siriusxi/hbca/service/ai/CustomerSupportAssistant.java`
- [Tool Wiring](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/config/BookingToolsConfig.java): tool config · Registers model-invokable tools for booking lookup and modification. · `src/main/java/rs/siriusxi/hbca/config/BookingToolsConfig.java`
- [System Prompt](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/resources/SystemMessage.st): prompt template · System message template that shapes assistant behavior. · `src/main/resources/SystemMessage.st`
- [Policy Text](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/resources/booking-terms.txt): knowledge source · Hotel booking terms used for retrieval and policy checks. · `src/main/resources/booking-terms.txt`

### Domain Model

Booking rules, entities, repositories, and mapping.

- [Booking Service](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/service/HotelBookingService.java): domain service · Central booking rules and persistence coordination. · `src/main/java/rs/siriusxi/hbca/service/HotelBookingService.java`
- [Details Mapper](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/service/mapper/BookingDetailsMapper.java): mapper · Converts booking entities into UI-friendly DTOs. · `src/main/java/rs/siriusxi/hbca/service/mapper/BookingDetailsMapper.java`
- [Booking](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/domain/Booking.java): entity · Core booking aggregate persisted in the database. · `src/main/java/rs/siriusxi/hbca/domain/Booking.java`
- [Customer](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/domain/Customer.java): entity · Customer record associated with bookings. · `src/main/java/rs/siriusxi/hbca/domain/Customer.java`
- [Repositories](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/repository/BookingRepository.java): Spring Data · Persistence access for bookings and customers. · `src/main/java/rs/siriusxi/hbca/repository/BookingRepository.java`

### Platform

Application bootstrap, configuration, persistence, and observability.

- [App Bootstrap](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/HCSAApplication.java): Spring Boot entrypoint · Application startup and vector-store initialization. · `src/main/java/rs/siriusxi/hbca/HCSAApplication.java`
- [App Config](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/config/AppConfig.java): configuration · General application wiring and runtime configuration support. · `src/main/java/rs/siriusxi/hbca/config/AppConfig.java`
- [Security](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/config/SecurityConfig.java): security config · Defines the request security boundary. · `src/main/java/rs/siriusxi/hbca/config/SecurityConfig.java`
- [Observability](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/java/rs/siriusxi/hbca/config/ContextPropagationConfiguration.java): telemetry config · Trace propagation, logging enrichment, and OpenTelemetry setup. · `src/main/java/rs/siriusxi/hbca/config/ContextPropagationConfiguration.java`
- [Data Layer](https://github.com/mohamed-taman/hotel-booking-ai-assistant/blob/main/src/main/resources/db/migration/V1__Create_schema.sql): persistence setup · Flyway migrations and application data source/runtime configuration. · `src/main/resources/db/migration/V1__Create_schema.sql`

## Connections

- React UI → Chat View: renders · The browser client mounts the main view.
- Chat View → Message UI: uses · The view composes message components.
- React UI → Assistant API: calls · UI requests chat responses from the assistant service.
- React UI → Booking API: calls · UI requests booking data from the booking service.
- Static Assets → React UI: styles · Shared static resources support the client UI.
- Assistant API → Support Assistant: delegates · UI boundary forwards conversation work to the AI orchestration layer.
- Support Assistant → Tool Wiring: invokes · Assistant can call booking tools during conversation.
- Support Assistant → System Prompt: shaped by · Prompt template guides assistant behavior.
- Support Assistant → Policy Text: retrieves · Policy text supports answer grounding and validation.
- Tool Wiring → Booking Service: executes · Tools route real actions into the booking service.
- Booking API → Details Mapper: formats · Booking UI service returns DTO-shaped data.
- Booking Service → Repositories: persists via · Booking logic delegates storage access to repositories.
- Booking Service → Booking: manages · Service operates on booking entities.
- Booking Service → Customer: reads/writes · Service coordinates customer data as part of booking operations.
- Details Mapper → Booking: maps · Mapper transforms booking entities for the UI.
- App Bootstrap → App Config: starts with · Bootstrap wires the application context.
- App Bootstrap → Data Layer: initializes · Startup ties into schema, seed data, and database setup.
- App Config → Security: includes · Configuration assembles security concerns.
- App Config → Observability: includes · Configuration assembles logging and telemetry concerns.
- Observability → Data Layer: exports · Observability can emit runtime signals around the data layer.
- Assistant API → Security: protected by · Assistant endpoints are subject to security configuration.
- Booking API → Security: protected by · Booking endpoints are subject to security configuration.