🏥 ClinIQ — AI Receptionist & Healthcare Assistant

ClinIQ is an intelligent, multi-agent AI receptionist system designed for medical clinics. Built as a monorepo, ClinIQ combines a React + Vite frontend interface, an Express + LangGraph AI agent backend, and a dedicated Model Context Protocol (MCP) database server connected to MongoDB and Nodemailer.

---

🌟 Key Features

• 🩺 Doctor Availability Lookup: Dynamically fetches and organizes doctor slots chronologically in 12-hour AM/PM format (Morning slots first, followed by Afternoon/Evening slots) with clean tick (✅) and cross (❌) status indicators.
• 📅 Atomic Appointment Booking: Real-time slot booking in MongoDB with race-condition protection.
• ✉️ Automated Confirmation Emails: Automatic email dispatch via Nodemailer (Gmail / SMTP) immediately upon booking confirmation, delivering complete appointment details to the patient.
• 🛡️ Safety & Security Guardrails:
  • Instant Emergency Interception: Detects crisis keywords (e.g., chest pain, shortness of breath) pre-LLM and instructs patients to call emergency services (911).
  • Prompt Leak Protection: Blocks prompt injection and developer instruction disclosure attempts.
  • Input Sanitization: XSS defense and regex validation.
• 📚 RAG Knowledge Base: Vector-search RAG pipeline that answers clinic FAQs on fasting, cancellations, copayments, and operating hours using official policy documentation.
• 📊 Detailed Process Logging: Transparent console logs displaying step-by-step progress ([TOOL CALLING], [GUARDRAIL PASSED], [TOOL SUCCESS], [TOOL FAILED]).

---

📁 Repository Structure

ClinIQ/
├── backend/                  # Node.js + Express API server & LangGraph AI Agent
│   ├── src/
│   │   ├── agents/           # LangGraph Agent state graph & node definitions
│   │   ├── controllers/      # Chat & Slot REST API endpoints
│   │   ├── guardrails/       # Safety guardrails & pre-LLM regex filters
│   │   ├── rag/              # Local vector store & policy document retriever
│   │   ├── models/           # Mongoose Slot data schema
│   │   └── server.js         # Backend server entry point (Port 8080)
│   └── .env                  # Backend environment variables
├── frontend/                 # React 19 + Vite + Tailwind CSS User Interface
│   ├── src/                  # React components & UI chat interface
│   └── package.json
├── mcp-db/                   # Model Context Protocol (MCP) Database & Email Server
│   ├── models/               # MongoDB Slot schema for MCP
│   ├── tools/                # MCP Tools (availability, booking, email dispatch)
│   ├── scripts/              # Seed database helper script
│   ├── mcp-server.js         # MCP server entry point (stdio transport)
│   └── .env                  # MCP database & Nodemailer SMTP credentials
├── tests/                    # Unit & Integration test suite
└── package.json              # Monorepo test runner script

---

⚙️ Environment Configuration (.env)

Create .env files in backend/ and mcp-db/ with the following variables:

mcp-db/.env & backend/.env

# Server Config
PORT=8080

# Database Config
MONGO_URI=mongodb://127.0.0.1:27017/clinic_mvp

# AI Agent API Key (OpenRouter / OpenAI)
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Nodemailer SMTP Email Credentials (e.g. Gmail)
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_gmail_app_password
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587

💡 Gmail App Password Note: For Gmail, generate a 16-character App Password under Google Account Security settings. Spaces in the password string are automatically sanitized by the email tool.

---

🚀 Getting Started

1. Prerequisites

• Node.js: v18+ or v22+
• MongoDB: Local MongoDB instance running on 127.0.0.1:27017

2. Install Dependencies

Install packages in all three sub-directories:

# Install backend dependencies
cd backend && npm install

# Install mcp-db dependencies
cd ../mcp-db && npm install

# Install frontend dependencies
cd ../frontend && npm install

3. Start Backend & MCP Database Server

From the backend directory:

cd backend
node src/server.js

The backend server will start on port 8080, automatically connect to MongoDB, load the RAG vector store, and initialize the MCP Database Server via stdio.

4. Start Frontend UI

From the frontend directory:

cd frontend
npm run dev

Open http://localhost:5173 in your browser to interact with the ClinIQ Smart Assistant.

---

🧪 Running Tests

Run the full test suite from the root directory:

npm test

This executes unit and integration tests covering safety guardrails, MCP database tools, slot chronological sorting, and chat endpoints.

---

🛠️ MCP Tools Reference

Tool Name	Parameters	Description
check_doctor_availability	date	Returns sorted 12-hour AM/PM available and booked doctor slots for a given date.
book_appointment	doctorName, date, time, patientName, patientPhone, patientEmail	Atomically updates MongoDB slot status to BOOKED and triggers email confirmation.
send_confirmation_email	patientEmail, patientName, doctorName, date, time	Sends an official HTML confirmation email to the patient using Nodemailer.
search_clinic_policy	query	Queries local vector embeddings for clinic policy FAQs and guidelines.

---

📜 License

This project is licensed under the ISC License.