# VaaniMitra AI Front Desk & Practice Automation OS — Full Technical Reference

> Comprehensive architectural specification, API reference, MCP tool catalog, and conversational guidelines for Large Language Models, AI Web Crawlers, and Autonomous Voice Agents.

---

## 1. Executive Summary & Value Proposition

VaaniMitra is an autonomous AI front-desk receptionist and practice management platform built for healthcare practices (clinics, hospitals, diagnostics, dental, dermatology) and appointment-based businesses across India.

### Key Problems Solved:
1. **Missed Patient Inbound Calls**: Traditional clinics miss up to 35% of patient calls during peak hours or after-hours. VaaniMitra answers 100% of calls instantly with zero hold time.
2. **Double-Bookings**: Doctors often book offline while online appointments overlap. VaaniMitra continuously monitors Google Calendar FreeBusy ranges to guarantee zero conflicting slots.
3. **No-Shows**: Up to 25% of clinic appointments result in no-shows. VaaniMitra runs proactive outbound reminder calls and WhatsApp confirmation templates to decrease no-shows below 5%.
4. **Language Barriers**: Patients in India naturally speak a blend of Hindi and English (Hinglish). VaaniMitra's conversational pipeline handles colloquial Hinglish, accent variations, and medical symptom descriptions effortlessly.

---

## 2. Technical Architecture & Component Topology

```
[Inbound Patient / Caller]
       │
       ▼ (SIP / Telephony Trunk)
[AI Voice Agent (Dograh :8081)]
       │
       ▼ (Model Context Protocol / SSE Stream)
[Backend V2 API Engine (:3000)] ───► [Google Calendar API (OAuth 2.0)]
       │                        ───► [Wati WhatsApp API]
       │                        ───► [Brevo Transactional SMTP]
       │                        ───► [PostgreSQL 16 (:5435)]
       │
       ▼ (HTTP REST / JWT Auth)
[VaaniMitra Web Dashboard (:5174)]
       │
       ▼ (Inter-service API Keys)
[VaaniNova Universal Billing (:3001)] ───► [Razorpay Payment Gateway]
```

---

## 3. Model Context Protocol (MCP) Interface for AI Agents

VaaniMitra implements the official Model Context Protocol (MCP) specification to provide autonomous voice agents with live clinic tools.

### Transports:
- **Server-Sent Events (SSE)**: `GET /mcp/sse` (Streams protocol handshake and tool execution events).
- **Stateless HTTP**: `POST /mcp/message` or `POST /mcp/sse` (Receives JSON-RPC 2.0 tool call requests).

### Available Tools:

#### `check_slot`
- **Description**: Checks available doctor consultation slots for a specific date.
- **Parameters**:
  - `businessId` (string, required): The unique UUID/CUID of the clinic.
  - `date` (string, required, YYYY-MM-DD): The date to search for openings.
- **Output**: Array of available 24-hour time strings (e.g. `["10:00", "10:30", "11:00", "16:30"]`).

#### `book_appointment`
- **Description**: Confirms and locks an appointment slot for a patient. Creates Google Calendar event and database records.
- **Parameters**:
  - `businessId` (string, required): Clinic ID.
  - `customerName` (string, required): Full name of the patient.
  - `phoneNumber` (string, required): E.164 formatted phone number (e.g. `+919876543210`).
  - `slotDatetime` (string, required, ISO 8601): Complete timestamp (e.g. `2026-09-22T10:30:00.000Z`).
  - `message` (string, optional): Reason for visit or symptoms described.
- **Output**: Booking confirmation object with `id`, `status: "BOOKED"`, and formatted local time strings.

#### `cancel_appointment`
- **Description**: Cancels a previously scheduled appointment and releases the slot.
- **Parameters**:
  - `appointmentId` (string, required): Unique booking ID.
  - `reason` (string, optional): Cancellation explanation.

#### `reschedule_appointment`
- **Description**: Modifies an existing appointment to a new available time slot.
- **Parameters**:
  - `id` (string, required): Existing booking ID.
  - `newSlotDatetime` (string, required): New target ISO timestamp.

#### `resolve_transfer`
- **Description**: Escalates call to emergency phone numbers or human receptionist.
- **Parameters**:
  - `businessId` (string, required): Clinic ID.
  - `reason` (string, required): Why human transfer is requested (e.g. medical emergency, complex procedure).

---

## 4. Public REST API Endpoints

### 1. Slot Discovery
```http
GET /api/appointment/slots?businessId=cmu49s0ir0002c878d64b2avz&date=2026-09-22
Content-Type: application/json
```
**Response (200 OK):**
```json
{
  "success": true,
  "businessId": "cmu49s0ir0002c878d64b2avz",
  "date": "2026-09-22",
  "slots": ["09:00", "09:30", "10:00", "10:30", "11:00", "17:00", "17:30", "18:00"],
  "count": 8
}
```

### 2. Patient Appointment Booking
```http
POST /api/appointment/book
Content-Type: application/json

{
  "businessId": "cmu49s0ir0002c878d64b2avz",
  "patientName": "Aarav Sharma",
  "phoneNumber": "+919876543210",
  "slotDatetime": "2026-09-22T10:00:00.000Z",
  "message": "Routine dental checkup"
}
```
**Response (201 Created):**
```json
{
  "success": true,
  "bookingId": "cmub1wiuu0006xw78o9xx1npq",
  "customerName": "Aarav Sharma",
  "phoneNumber": "+919876543210",
  "slotDatetime": "2026-09-22T10:00:00.000Z",
  "formattedAppointmentTime": "Tuesday, September 22, 2026, 03:30 PM (Asia/Kolkata)",
  "status": "BOOKED"
}
```

---

## 5. Telephony & Outbound Campaigns

- **Outbound Batch Dialer**: Supports CSV contact list uploads, retry logic for unanswered calls, and disposition tracking (`COMPLETED`, `BUSY`, `NO_ANSWER`, `FAILED`).
- **Do-Not-Call (DNC) Registry**: Protects clinic reputation by filtering numbers registered on promotional blocklists before any outbound campaign dialer runs.
- **Dynamic Objection Library**: Injects pre-trained rebuttals for common patient hesitations (consultation fees, distance, waiting times).

---

## 6. Security, Authentication & Cryptography

- **Google OAuth 2.0 Security**: Refresh and access tokens are encrypted at rest using AES-256-GCM authenticated encryption.
- **RBAC**: Multi-tenant isolation ensuring clinic staff cannot view or alter another clinic's patient records.
- **Payment Idempotency**: In-memory mutex maps and database constraint auditing ensure concurrent Razorpay webhooks and browser redirects never allocate duplicate minutes.

---

## 7. Metadata & Contact Information

- **Product Name**: VaaniMitra AI Front Desk & Practice Automation OS
- **Parent Company**: VaaniNova Technologies
- **Target Audience**: Clinics, Doctors, Diagnostic Centers, Hospitals, Polyclinics in India
- **Primary Languages**: Hinglish, Hindi, English
- **Website**: https://vaanimitra.in/
- **Documentation**: https://vaanimitra.in/llms.txt