# usermangcut-ai/hotelchatbot architecture

> Architecture diagram of the GitHub repository usermangcut-ai/hotelchatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/usermangcut-ai/hotelchatbot
- Repository: https://github.com/usermangcut-ai/hotelchatbot

## Overview

Shanghai Resort is a Vietnamese hotel-resort chatbot and operations portal. Guests can ask grounded questions, check availability, and request a booking form; the booking is recorded only after they confirm in the UI. Staying guests can submit restaurant/spa requests and support requests, while staff process requests and admins manage bookings and accounts. The graph combines README-described capabilities with sampled wiring; some route and domain details are documented but their implementations were not sampled, so uncertain internal calls are omitted.

Main entry points: [`api/main.py`](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/main.py) (FastAPI app), [`frontend/src/App.tsx`](https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/App.tsx) (Web app), [`agent/agent.py`](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/agent.py) (Agent runtime), [`agent/db.py`](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/db.py) (Hotel database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Guest interface"]
  node_app["Web app<br/>[App.tsx]"]
  node_home["Chat home<br/>[Home.tsx]"]
  node_booking_ui["Booking page<br/>[BookingPage.tsx]"]
  node_service_ui["Service form"]
  node_guest_ui["Guest account"]
  node_staff_ui["Staff queue<br/>[StaffPage.tsx]"]
  node_admin_ui["Admin console<br/>[AdminPage.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
end

subgraph group_api["HTTP and access"]
  node_server["FastAPI app<br/>[main.py]"]
  node_chat_route["Chat route<br/>[chat.py]"]
  node_booking_route["Booking routes<br/>[bookings.py]"]
  node_service_route["Service route"]
  node_auth_route["Auth routes<br/>[auth.py]"]
  node_admin_routes["Admin routes<br/>[admin.py]"]
  node_staff_routes["Staff routes<br/>[staff.py]"]
  node_guest_routes["Guest routes<br/>[guest.py]"]
  node_auth["Session access<br/>[auth.py]"]
end

subgraph group_agent["Chat agent"]
  node_agent_runtime["Agent runtime<br/>[agent.py]"]
  node_guardrail["Guardrail<br/>[guardrail.py]"]
  node_memory["Conversation memory<br/>[memory.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_knowledge["Resort knowledge<br/>[knowledge.py]"]
  node_prompt["Prompt builder<br/>[prompts.py]"]
  node_photos["Photo selection<br/>[photos.py]"]
  node_trace["Chat trace<br/>[trace.py]"]
  node_llm_client["LLM client<br/>[llm_client.py]"]
end

subgraph group_ops["Resort operations"]
  node_admin_ops["Booking and account management<br/>[admin.py]"]
  node_staff_ops["Request handling<br/>[staff.py]"]
  node_guest_ops["Guest support<br/>[guest.py]"]
end

subgraph group_state["Data and providers"]
  node_database[("Hotel database<br/>[db.py]")]
end

node_guest(("Guest"))
node_staff_user(("Staff user"))
node_admin_user(("Administrator"))
node_llm_provider{{"LLM provider"}}

node_guest -->|"uses"| node_app
node_staff_user -->|"uses"| node_app
node_admin_user -->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_booking_ui
node_app -->|"routes to"| node_service_ui
node_app -->|"routes to"| node_guest_ui
node_app -->|"routes to"| node_staff_ui
node_app -->|"routes to"| node_admin_ui
node_home -->|"requests"| node_frontend_api
node_booking_ui -->|"requests"| node_frontend_api
node_service_ui -->|"submits"| node_frontend_api
node_guest_ui -->|"requests"| node_frontend_api
node_staff_ui -->|"requests"| node_frontend_api
node_admin_ui -->|"requests"| node_frontend_api
node_frontend_api -->|"calls API"| node_server
node_server -->|"dispatches"| node_chat_route
node_server -->|"dispatches"| node_booking_route
node_server -->|"dispatches"| node_service_route
node_server -->|"dispatches"| node_auth_route
node_server -->|"dispatches"| node_admin_routes
node_server -->|"dispatches"| node_staff_routes
node_server -->|"dispatches"| node_guest_routes
node_chat_route -->|"invokes"| node_agent_runtime
node_agent_runtime -->|"checks input"| node_guardrail
node_agent_runtime -->|"loads context"| node_memory
node_agent_runtime -->|"uses prompt"| node_prompt
node_agent_runtime -->|"requests completion"| node_llm_client
node_llm_client -->|"sends messages"| node_llm_provider
node_agent_runtime -->|"dispatches calls"| node_tools
node_tools -->|"looks up facts"| node_knowledge
node_tools -->|"checks availability"| node_database
node_tools -->|"selects imagery"| node_photos
node_agent_runtime -->|"records turn"| node_trace
node_booking_route -->|"confirms booking"| node_database
node_service_route -->|"requires guest role"| node_auth
node_auth_route -->|"reads/writes sessions"| node_database
node_auth -->|"checks session"| node_database
node_admin_routes -->|"manages records"| node_database
node_staff_routes -->|"updates requests"| node_database
node_guest_routes -->|"reads guest data"| node_database
node_admin_routes -->|"serves"| node_admin_ops
node_staff_routes -->|"serves"| node_staff_ops
node_guest_routes -->|"serves"| node_guest_ops
node_service_route -->|"creates request"| node_database
node_server -->|"serves images"| node_photos

click node_app "https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/Home.tsx"
click node_booking_ui "https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/BookingPage.tsx"
click node_service_ui "https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/ServiceRequestPage.tsx"
click node_guest_ui "https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/GuestAccountPage.tsx"
click node_staff_ui "https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/StaffPage.tsx"
click node_admin_ui "https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/AdminPage.tsx"
click node_frontend_api "https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/api.ts"
click node_server "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/main.py"
click node_chat_route "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/chat.py"
click node_booking_route "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/bookings.py"
click node_service_route "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/service_requests.py"
click node_auth_route "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/auth.py"
click node_admin_routes "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/admin.py"
click node_staff_routes "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/staff.py"
click node_guest_routes "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/guest.py"
click node_auth "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/auth.py"
click node_agent_runtime "https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/agent.py"
click node_guardrail "https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/guardrail.py"
click node_memory "https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/memory.py"
click node_tools "https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/tools.py"
click node_knowledge "https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/knowledge.py"
click node_prompt "https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/prompts.py"
click node_photos "https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/photos.py"
click node_trace "https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/trace.py"
click node_llm_client "https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/llm_client.py"
click node_admin_ops "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/admin.py"
click node_staff_ops "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/staff.py"
click node_guest_ops "https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/guest.py"
click node_database "https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/db.py"

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_app,node_home,node_booking_ui,node_service_ui,node_guest_ui,node_staff_ui,node_admin_ui,node_frontend_api,node_staff_user toneBlue
class node_server,node_chat_route,node_booking_route,node_service_route,node_auth_route,node_admin_routes,node_staff_routes,node_guest_routes,node_auth toneAmber
class node_agent_runtime,node_guardrail,node_memory,node_tools,node_knowledge,node_prompt,node_photos,node_trace,node_llm_client toneMint
class node_admin_ops,node_staff_ops,node_guest_ops toneRose
class node_database,node_guest,node_admin_user,node_llm_provider toneIndigo
```

## Components

### Guest interface

- [Web app](https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat home](https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/Home.tsx): `frontend/src/pages/Home.tsx`
- [Booking page](https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/BookingPage.tsx): `frontend/src/pages/BookingPage.tsx`
- [Service form](https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/ServiceRequestPage.tsx): `frontend/src/pages/ServiceRequestPage.tsx`
- [Guest account](https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/GuestAccountPage.tsx): `frontend/src/pages/GuestAccountPage.tsx`
- [Staff queue](https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/StaffPage.tsx): `frontend/src/pages/StaffPage.tsx`
- [Admin console](https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/pages/AdminPage.tsx): `frontend/src/pages/AdminPage.tsx`
- [API client](https://github.com/usermangcut-ai/hotelchatbot/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### HTTP and access

- [FastAPI app](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/main.py): `api/main.py`
- [Chat route](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/chat.py): `api/routes/chat.py`
- [Booking routes](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/bookings.py): `api/routes/bookings.py`
- [Service route](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/service_requests.py): `api/routes/service_requests.py`
- [Auth routes](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/auth.py): `api/routes/auth.py`
- [Admin routes](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/admin.py): `api/routes/admin.py`
- [Staff routes](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/staff.py): `api/routes/staff.py`
- [Guest routes](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/guest.py): `api/routes/guest.py`
- [Session access](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/auth.py): `api/auth.py`

### Chat agent

- [Agent runtime](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/agent.py): `agent/agent.py`
- [Guardrail](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/guardrail.py): `agent/guardrail.py`
- [Conversation memory](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/memory.py): `agent/memory.py`
- [Agent tools](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/tools.py): `agent/tools.py`
- [Resort knowledge](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/knowledge.py): `agent/knowledge.py`
- [Prompt builder](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/prompts.py): `agent/prompts.py`
- [Photo selection](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/photos.py): `agent/photos.py`
- [Chat trace](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/trace.py): `agent/trace.py`
- [LLM client](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/llm_client.py): `agent/llm_client.py`

### Resort operations

- [Booking and account management](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/admin.py): `api/routes/admin.py`
- [Request handling](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/staff.py): `api/routes/staff.py`
- [Guest support](https://github.com/usermangcut-ai/hotelchatbot/blob/main/api/routes/guest.py): `api/routes/guest.py`

### Data and providers

- [Hotel database](https://github.com/usermangcut-ai/hotelchatbot/blob/main/agent/db.py): `agent/db.py`

### Other components

- **Guest**
- **Staff user**
- **Administrator**
- **LLM provider**

## Connections

- Guest → Web app: uses
- Staff user → Web app: uses
- Administrator → Web app: uses
- Web app → Chat home: routes to
- Web app → Booking page: routes to
- Web app → Service form: routes to
- Web app → Guest account: routes to
- Web app → Staff queue: routes to
- Web app → Admin console: routes to
- Chat home → API client: requests
- Booking page → API client: requests
- Service form → API client: submits
- Guest account → API client: requests
- Staff queue → API client: requests
- Admin console → API client: requests
- API client → FastAPI app: calls API
- FastAPI app → Chat route: dispatches
- FastAPI app → Booking routes: dispatches
- FastAPI app → Service route: dispatches
- FastAPI app → Auth routes: dispatches
- FastAPI app → Admin routes: dispatches
- FastAPI app → Staff routes: dispatches
- FastAPI app → Guest routes: dispatches
- Chat route → Agent runtime: invokes
- Agent runtime → Guardrail: checks input
- Agent runtime → Conversation memory: loads context
- Agent runtime → Prompt builder: uses prompt
- Agent runtime → LLM client: requests completion
- LLM client → LLM provider: sends messages
- Agent runtime → Agent tools: dispatches calls
- Agent tools → Resort knowledge: looks up facts
- Agent tools → Hotel database: checks availability
- Agent tools → Photo selection: selects imagery
- Agent runtime → Chat trace: records turn
- Booking routes → Hotel database: confirms booking
- Service route → Session access: requires guest role
- Auth routes → Hotel database: reads/writes sessions
- Session access → Hotel database: checks session
- Admin routes → Hotel database: manages records
- Staff routes → Hotel database: updates requests
- Guest routes → Hotel database: reads guest data
- Admin routes → Booking and account management: serves
- Staff routes → Request handling: serves
- Guest routes → Guest support: serves
- Service route → Hotel database: creates request
- FastAPI app → Photo selection: serves images