HCIMS AI - Hotel Complaint Intelligence Management System

HCIMS AI is an AI-powered hotel complaint management platform that turns guest feedback into trackable department tickets, routes issues to the correct team, validates resolution proof, and gives admins operational analytics.

The project is organized as a monorepo with separate frontend, backend/ML, and proof-validation reference folders. The existing folder names are preserved so the current demo scripts and imports keep working.

Key Features

• AI-based complaint vs appreciation detection
• Department routing for Housekeeping, Engineering & Maintenance, Food & Beverage, IT Support, and Front Office
• Priority assignment with ticket deadlines
• Admin dashboard for uploads, tickets, staff accounts, appreciations, analytics, notifications, and activity logs
• Department staff dashboard for assigned tickets and proof-based resolution
• Supabase authentication, storage, database tables, and row-level security policies
• Sarvam-powered UI translation and multilingual voice input
• Nonescape-based synthetic AI image detection for resolution proof validation
• Analytics with date filters, status distribution, department ticket health, recurring issues, and dark mode

Repository Structure

HCIMS-AI/
|-- hcims-ai-main/                       # React + Vite frontend
|   |-- src/                             # UI pages, components, contexts, hooks
|   |-- supabase/                        # Supabase functions and migrations
|   |-- package.json                     # Frontend scripts and dependencies
|   `-- .env.example                     # Frontend environment template
|-- HCIMS-AI-Complaint-System-main/      # FastAPI backend + ML pipeline
|   |-- api.py                           # API routes for prediction, staff admin, translation, proof resolution
|   |-- src/                             # Prediction and proof validation logic
|   |-- data/                            # Training/input data
|   |-- mlops/                           # MLOps support files
|   |-- requirements.txt                 # Backend dependencies
|   `-- .env.example                     # Backend environment template
|-- nonescape-master/                    # Nonescape reference/source used for proof validation setup
|-- start.ps1                            # Local development startup helper
`-- README.md                            # Project overview

Tech Stack

Frontend

• React 18
• TypeScript
• Vite
• Tailwind CSS
• shadcn/ui
• Recharts
• Supabase JS client
• Sarvam translation integration through the backend

Backend and AI

• Python
• FastAPI
• Uvicorn
• scikit-learn, sentence-transformers, transformers, torch
• Supabase Admin REST/Auth integration
• Sarvam AI for text translation and speech-to-text
• Nonescape for AI-generated proof image detection

Data and Platform

• Supabase Auth
• Supabase Postgres with RLS
• Supabase Storage for proof images
• DVC/MLflow support for ML workflow tracking

Local Setup

1. Clone the repository

git clone <repo-url>
cd HCIMS-AI

2. Configure environment variables

Create frontend env:

copy hcims-ai-main\.env.example hcims-ai-main\.env

Create backend env:

copy HCIMS-AI-Complaint-System-main\.env.example HCIMS-AI-Complaint-System-main\.env

Fill in the Supabase and Sarvam values before running the app.

3. Install frontend dependencies

cd hcims-ai-main
npm install

4. Install backend dependencies

cd ..\HCIMS-AI-Complaint-System-main
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

5. Start backend

cd HCIMS-AI-Complaint-System-main
uvicorn api:app --host 0.0.0.0 --port 8001

6. Start frontend

cd hcims-ai-main
npm run dev -- --host 0.0.0.0 --port 8080

Open:

http://localhost:8080

Useful Scripts

Frontend:

npm run dev
npm run build
npm test

Backend:

uvicorn api:app --host 0.0.0.0 --port 8001

Root helper:

.\start.ps1

Docker Deployment

The project is dockerized for local container-based deployment using:

• docker-compose.yml
• HCIMS-AI-Complaint-System-main/Dockerfile
• hcims-ai-main/Dockerfile

Build and run

docker compose build
docker compose up

Run in background

docker compose up -d

Stop containers

docker compose down

Container endpoints

• Frontend: http://localhost:8080
• Backend API docs: http://localhost:8001/docs

Notes

• The frontend is served through Nginx inside Docker.
• The backend runs FastAPI with Uvicorn inside Docker.
• The Docker setup uses cloud Supabase, not a local Postgres container.
• In Docker mode, the frontend talks to the backend through /api proxying.

Environment Variables

Frontend:

VITE_SUPABASE_PROJECT_ID=
VITE_SUPABASE_PUBLISHABLE_KEY=
VITE_SUPABASE_URL=
VITE_API_URL=http://localhost:8001

Backend:

SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
SARVAM_API_KEY=
NONESCAPE_MODEL_PATH=artifacts/nonescape-mini-v0.safetensors
AI_IMAGE_CONFIDENCE_THRESHOLD=0.75
PROOF_IMAGE_MAX_BYTES=10485760

Demo Flow

1. Sign in as an admin.
2. Upload a CSV of guest reviews.
3. Let the backend classify reviews into complaints and appreciations.
4. Review generated tickets in the admin ticket table.
5. Create department staff accounts and share credentials.
6. Sign in as department staff and resolve assigned tickets with proof.
7. Review analytics by date range and switch between light/dark mode.

Deployment Status

Current status of the project:

• Frontend and backend both run successfully in Docker containers
• Local containerized deployment is complete
• Local browser access works through localhost:8080
• Backend API is exposed through localhost:8001
• Public cloud deployment is not yet configured

"The system has been fully containerized and can be deployed locally as isolated frontend and backend services. Public cloud deployment is the next deployment stage."

MLOps and Versioning Support

The project already includes the foundations of an MLOps workflow:

• DVC files present in the backend project
• MLflow local tracking database present in the backend project
• serialized ML artifacts stored under artifacts/

Current MLOps-related files

• .dvc/
• dvc.yaml
• dvc.lock
• mlflow.db

What this enables

• versioning of datasets and ML artifacts
• reproducible ML pipeline steps
• experiment tracking for model training and evaluation
• cleaner collaboration between application and ML development

"The project supports MLOps practices through DVC for artifact/data versioning and MLflow for experiment tracking, making the ML pipeline reproducible and easier to maintain."