# VaaniMitra AI Front Desk & Practice Automation OS

> Enterprise 24/7 bilingual (Hinglish/English) AI receptionist, Google Calendar dynamic scheduling engine, WhatsApp confirmation system, and clinic practice operating system.

VaaniMitra is an autonomous AI front-desk receptionist built specifically for clinics, healthcare practices, hospitals, and appointment-driven service businesses in India. It answers inbound phone calls, schedules doctor appointments directly into Google Calendar with zero double-bookings, dispatches instant WhatsApp notifications, executes outbound patient reminder campaigns, and tracks prepaid AI calling minutes.

## Core Capabilities

- **Bilingual Voice Receptionist**: Fluent, empathetic conversational AI speaking natural Hinglish and English. Handles patient inquiries, clinic hours, doctor specialties, fees, and location queries.
- **Dynamic 2-Way Google Calendar Scheduling**: Computes available 30-minute consultation slots in real-time by cross-referencing clinic operating hours, Google Calendar FreeBusy ranges, and internal database reservations.
- **Model Context Protocol (MCP) Integration**: Native SSE (`/mcp/sse`) and stateless HTTP (`/mcp/message`) transports exposing live scheduling tools to AI voice agents (Dograh, Retell, Vapi, Claude, ChatGPT).
- **Outbound Patient Reminder Campaigns**: Proactive outbound phone calls and WhatsApp messages scheduled before clinic appointments to reduce patient no-show rates.
- **Clinic Emergency & Status Toggles**: Instant management controls to toggle clinic status between `OPEN`, `CLOSED`, and `EMERGENCY_ONLY` with automatic fallback call forwarding.
- **Prepaid Minute Quota & Universal Billing**: Integrated with VaaniNova Universal Billing microservice, supporting plan subscriptions (Plan A, Plan B, Plan C), voice minute top-ups, and Razorpay payments.
- **Knowledge Base Retrieval**: Instant access to doctor bios, treatment brochures, and custom clinic FAQs during patient phone conversations.

## Model Context Protocol (MCP) Tools for AI Agents

AI voice agents communicate with VaaniMitra Backend V2 via Model Context Protocol tools:

- `check_slot`: Queries available consultation slots for a specific doctor or clinic on a given date.
- `book_appointment`: Reserves a verified slot, creates an event in Google Calendar, inserts the patient into the clinic roster, and triggers a WhatsApp confirmation.
- `cancel_appointment`: Cancels an existing booking and frees up the calendar slot.
- `reschedule_appointment`: Moves an appointment to a newly selected available slot.
- `resolve_transfer`: Escalates urgent medical queries or human assistance requests to the clinic emergency phone number.
- `get_business_info`: Fetches clinic timings, address, consulting doctors, and operational status.

## Public Web APIs for Patient Portals & Widgets

- `GET /api/appointment/slots?businessId={id}&date={YYYY-MM-DD}`: Returns verified available consultation time slots for the requested date.
- `POST /api/appointment/check-slot`: Checks whether a specific timestamp is free.
- `POST /api/appointment/book`: Books an appointment for a patient without requiring admin authentication. Body parameters: `businessId`, `customerName`, `phoneNumber`, `slotDatetime`, `message`.

## System Architecture

- **Frontend**: React 18, Vite 5, Tailwind CSS v4, TanStack Query (Port 5174).
- **Backend API**: Express 5, TypeScript, Prisma ORM, PostgreSQL (Port 3000).
- **Billing Microservice**: VaaniNova Universal Billing, Razorpay, Invoices (Port 3001).
- **Voice Telephony**: Dograh / Retell SIP audio gateway (Port 8081).
- **Background Workflows**: Kestra workflow orchestrator for automated cron reminders.

## Deep Documentation Links

- Full Technical LLM Specifications: https://vaanimitra.in/llms-full.txt
- Frontend Dashboard: https://vaanimitra.in/
- Appointments Roster: https://vaanimitra.in/appointments
- XML Sitemap: https://vaanimitra.in/sitemap.xml