elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/07-APPOINTMENTS.md

@@ -0,0 +1,849 @@
+# Appointments
+
+> Full appointment lifecycle: Google Calendar integration, booking, cancellation, reminders, and batch validation.
+> Last updated: 2026-04-02
+
+---
+
+## 1. Google Calendar Integration
+
+Each clinic connects its own Google Calendar through an OAuth2 flow. The connection is stored in the `clinic_calendar_connections` table, one row per clinic.
+
+### 1.1 Data Model: ClinicCalendarConnection
+
+```
+clinic_calendar_connections
+  calcn_id                       UUID PK
+  calcn_clinic_id                UUID UNIQUE FK -> clinics
+  calcn_google_email             String?        -- Google account email
+  calcn_encrypted_refresh_token  String?        -- AES-256-GCM encrypted
+  calcn_calendar_id              String?        -- Selected Google Calendar ID
+  calcn_calendar_name            String?
+  calcn_timezone                 String         -- default "Europe/Istanbul"
+  calcn_appointment_duration     Int            -- default 30 (minutes)
+  calcn_working_hours            JSONB          -- [{day, start, end}]
+  calcn_blocked_dates            JSONB          -- [{date, reason}]
+  calcn_connected_at             DateTime?
+  calcn_created_at               DateTime
+  calcn_updated_at               DateTime
+```
+
+**Key points:**
+- One-to-one with `clinics` via `calcn_clinic_id UNIQUE`.
+- `calcn_encrypted_refresh_token` uses AES-256-GCM encryption with the `GOOGLE_TOKEN_ENCRYPTION_KEY` environment variable. Never stored in plaintext.
+- `calcn_working_hours` is a JSON array of per-day schedules, e.g. `[{day: 1, start: "09:00", end: "18:00"}, ...]` where `day` is 0=Sunday through 6=Saturday.
+- `calcn_blocked_dates` stores holidays and closures, e.g. `[{date: "2026-04-23", reason: "Ulusal Egemenlik"}]`.
+
+### 1.2 OAuth2 Connection Flow
+
+```
+Admin clicks "Connect Google Calendar"
+  |
+  v
+GET /whatsapp/google-calendar/auth-url
+  |  Generate HMAC-signed state parameter: HMAC(clinicId + timestamp, GOOGLE_OAUTH_STATE_SECRET)
+  |  Build Google OAuth URL with scopes: calendar.readonly, calendar.events
+  |  Return URL to frontend
+  v
+Browser redirects to Google consent screen
+  |  User authorizes
+  v
+Google redirects to GET /google-calendar/callback?code=...&state=...
+  |  1. Verify state HMAC signature (prevents CSRF)
+  |  2. Exchange authorization code for tokens (POST to Google token endpoint)
+  |  3. Extract refresh_token from response
+  |  4. Encrypt refresh_token with AES-256-GCM using GOOGLE_TOKEN_ENCRYPTION_KEY
+  |  5. Store in clinic_calendar_connections.calcn_encrypted_refresh_token
+  |  6. Set calcn_connected_at = now()
+  |  7. Redirect browser to FRONTEND_URL/settings?calendar=connected
+  v
+Connection established
+```
+
+**Security:**
+- The callback route is unauthenticated (browser redirect from Google) but protected by the HMAC-signed state parameter.
+- Refresh tokens are encrypted at rest. The encryption key is a 32-byte hex string generated with `openssl rand -hex 32`.
+
+### 1.3 Token Management
+
+Google access tokens expire after ~1 hour. The system caches them in Redis and manages refresh with per-tenant mutexes to prevent race conditions.
+
+**Redis keys:**
+- `gcal:token:{clinicId}` -- cached access token, 50-minute TTL (shorter than Google's ~60min expiry)
+- `gcal:mutex:{clinicId}` -- refresh mutex, 10-second TTL
+
+**Access token resolution:**
+
+```
+Need access token for clinicId
+  |
+  v
+Check Redis: gcal:token:{clinicId}
+  |
+  +-- Cache hit --> return cached token
+  |
+  +-- Cache miss
+        |
+        v
+      Acquire mutex: SET gcal:mutex:{clinicId} NX EX 10
+        |
+        +-- Mutex acquired
+        |     |
+        |     v
+        |   Decrypt refresh_token from DB (AES-256-GCM)
+        |   POST to Google token endpoint with refresh_token
+        |   Receive new access_token
+        |   Cache in Redis with 50min TTL
+        |   Release mutex
+        |   Return access_token
+        |
+        +-- Mutex not acquired (another request is refreshing)
+              |
+              v
+            Wait briefly, retry Redis read
+            Return cached token (now populated by other request)
+```
+
+### 1.4 Disconnect Flow
+
+```
+POST /whatsapp/google-calendar/disconnect
+  |
+  v
+1. Delete clinic_calendar_connections row (or null out token fields)
+2. Delete Redis cache: gcal:token:{clinicId}
+3. Revoke token at Google (POST https://oauth2.googleapis.com/revoke)
+4. Remove any scheduled appointment reminder jobs from BullMQ
+```
+
+---
+
+## 2. Availability Checking
+
+When the AI calls `check_availability(date)`, the system computes available slots by layering three filters.
+
+### 2.1 Slot Duration Resolution
+
+When generating candidate slots, the system determines slot duration through a priority chain:
+
+```
+treatment.duration_minutes            (if a treatment is specified)
+  → doctor.profile_appointment_duration (if a doctor is specified)
+    → clinic.calcn_appointment_duration
+      → tenant.tenant_default_appt_duration (30 min fallback)
+```
+
+This means a specific treatment's duration takes highest priority, followed by the doctor's default appointment duration, then the clinic default.
+
+### 2.2 Slot Generation Algorithm
+
+```
+Input: date (YYYY-MM-DD), clinicId, doctorId? (optional), treatmentId? (optional)
+
+Step 0: Resolve slot duration
+  |  Apply the priority chain from Section 2.1
+  |
+
+Step 1: Blocked date check
+  |  Look up date in calcn_blocked_dates
+  |  If found --> return "Clinic closed: {reason}"
+  |
+Step 2: Working hours lookup
+  |  If doctorId is specified:
+  |    Look up doctor's profile_working_hours for matching day-of-week
+  |    If no entry for this day --> return "Doctor not available on this day"
+  |  Else:
+  |    Look up calcn_working_hours for matching day-of-week
+  |    If no entry for this day --> return "Clinic closed on this day"
+  |  Extract start_time and end_time (e.g., "09:00" to "18:00")
+  |
+Step 3: Generate candidate slots
+  |  From start_time to end_time, generate slots of resolved slot duration
+  |  Example (30min): 09:00, 09:30, 10:00, ..., 17:30
+  |
+Step 4: Google FreeBusy API call
+  |  POST https://www.googleapis.com/calendar/v3/freeBusy
+  |  Body: {
+  |    timeMin: "{date}T{start}:00+03:00",
+  |    timeMax: "{date}T{end}:00+03:00",
+  |    items: [{ id: calcn_calendar_id }]
+  |  }
+  |  Returns array of busy intervals: [{start, end}, ...]
+  |
+Step 5: Filter out busy slots
+  |  For each candidate slot, check if it overlaps any busy interval
+  |  Remove overlapping slots
+  |
+Step 6: Return available slots
+  |  Format as list of {start, end} ISO strings
+  |  Include total count and date
+```
+
+**Edge cases:**
+- Past dates are rejected before any calendar query.
+- The current date filters out slots already in the past (now + buffer).
+- Timezone handling uses `calcn_timezone` (default `Europe/Istanbul`) for all calculations.
+- When a doctor is specified, their `profile_working_hours` are used instead of the clinic-level working hours. If the doctor has no working hours configured, the clinic defaults are used as fallback.
+
+---
+
+## 3. Booking Flow
+
+### 3.1 Sequence Diagram
+
+```
+Patient (WhatsApp)          AI Agent            CalendarTools           GoogleCalendarService        DB / Events
+       |                       |                      |                          |                       |
+       |  "Book me for 10am"   |                      |                          |                       |
+       |---------------------->|                      |                          |                       |
+       |                       |                      |                          |                       |
+       |                       |  check_availability  |                          |                       |
+       |                       |  (date)              |                          |                       |
+       |                       |--------------------->|                          |                       |
+       |                       |                      |  FreeBusy API            |                       |
+       |                       |                      |------------------------->|                       |
+       |                       |                      |  available slots         |                       |
+       |                       |                      |<-------------------------|                       |
+       |                       |  slots               |                          |                       |
+       |                       |<---------------------|                          |                       |
+       |                       |                      |                          |                       |
+       |  "10:00 works"        |                      |                          |                       |
+       |---------------------->|                      |                          |                       |
+       |                       |                      |                          |                       |
+       |                       |  reserve_slot        |                          |                       |
+       |                       |  (name, start, end)  |                          |                       |
+       |                       |--------------------->|                          |                       |
+       |                       |                      |                          |                       |
+       |                       |                      |  1. Re-check FreeBusy   |                       |
+       |                       |                      |  (race protection)       |                       |
+       |                       |                      |------------------------->|                       |
+       |                       |                      |  still free              |                       |
+       |                       |                      |<-------------------------|                       |
+       |                       |                      |                          |                       |
+       |                       |                      |  2. Create Google event  |                       |
+       |                       |                      |  (with extendedProps)    |                       |
+       |                       |                      |------------------------->|                       |
+       |                       |                      |  event_id               |                       |
+       |                       |                      |<-------------------------|                       |
+       |                       |                      |                          |                       |
+       |                       |                      |  3. Emit appointment.created ------------------>|
+       |                       |                      |                          |                       |
+       |                       |                      |                          |    4. Create Appointment
+       |                       |                      |                          |    5. Send SMS (NetGSM)
+       |                       |                      |                          |    6. Schedule reminders
+       |                       |                      |                          |                       |
+       |                       |  confirmation        |                          |                       |
+       |                       |<---------------------|                          |                       |
+       |  "Confirmed: 10:00"   |                      |                          |                       |
+       |<----------------------|                      |                          |                       |
+```
+
+### 3.2 Step-by-Step
+
+1. **AI calls `check_availability(date)`** -- the CalendarTools handler runs the slot generation algorithm (Section 2.1) and returns available time slots.
+
+2. **AI calls `reserve_slot(patient_name, iso_start, iso_end, notes)`** -- this triggers the booking sequence:
+
+3. **Re-check FreeBusy (race protection)** -- between the availability check and the booking, another patient may have taken the slot. The service calls Google FreeBusy API again for the exact time window. If the slot is now busy, return an error to the AI so it can suggest alternatives.
+
+4. **Create Google Calendar event** -- if the slot is still free, create an event via the Calendar API:
+   ```
+   POST /calendar/v3/calendars/{calendarId}/events
+   {
+     summary: "{patient_name} - Randevu",
+     start: { dateTime: iso_start, timeZone: timezone },
+     end: { dateTime: iso_end, timeZone: timezone },
+     description: notes,
+     extendedProperties: {
+       private: {
+         source: "portal-asistan",
+         patient_phone: "+905551234567",
+         tenant_id: "uuid",
+         clinic_id: "uuid"
+       }
+     }
+   }
+   ```
+   The `extendedProperties.private.source = 'portal-asistan'` tag identifies events created by the system. The `patient_phone` property enables ownership verification for cancellation and listing.
+
+5. **Create Appointment record in DB** -- via EventEmitter (`appointment.created` event), fire-and-forget:
+   ```
+   appointments table:
+     appt_clinic_id        = clinicId (required)
+     appt_patient_id       = resolved from ToolContext.patientPhone → Patient lookup (required)
+     appt_doctor_id        = resolved from doctor_name param (nullable)
+     appt_treatment_id     = resolved from treatment context (nullable)
+     appt_google_event_id  = Google event ID
+     appt_patient_name     = from params or context (denormalized)
+     appt_patient_phone    = from ToolContext (denormalized)
+     appt_start_time       = iso_start
+     appt_end_time         = iso_end
+     appt_type             = 'appointment' (default for AI bookings)
+     appt_source           = 'whatsapp' | 'voice_call'
+     appt_status           = 'scheduled'
+     appt_chat_id          = from channelMetadata (nullable)
+     appt_session_id       = from channelMetadata (nullable)
+     appt_conversation_id  = from channelMetadata (nullable)
+   ```
+
+6. **SMS notification to clinic** -- NetGSM sends an SMS to the clinic's configured notification phones informing staff of the new booking.
+
+7. **Schedule appointment reminders** -- BullMQ delayed jobs are created (see Section 5 below).
+
+---
+
+## 4. Cancellation and Rescheduling
+
+### 4.1 Cancellation (`cancel_reservation`)
+
+**Parameters:** `{event_id}`
+
+**Flow:**
+1. Look up the Google Calendar event by `event_id`.
+2. **Ownership verification:** read `extendedProperties.private.patient_phone` from the event. Compare with `ctx.patientPhone`. If mismatch, return error -- patients can only cancel their own appointments.
+3. Delete the Google Calendar event via `DELETE /calendar/v3/calendars/{calendarId}/events/{eventId}`.
+4. Update the Appointment record: set `appt_status = 'cancelled'`, `appt_cancelled_at = now()`.
+5. Send SMS notification to the clinic about the cancellation.
+6. Remove scheduled reminder jobs from BullMQ (by job ID pattern `reminder:{appointmentId}:*`).
+
+### 4.2 Rescheduling (`reschedule_reservation`)
+
+**Parameters:** `{old_event_id, new_iso_start, new_iso_end, notes}`
+
+**Flow:**
+1. Verify ownership of `old_event_id` (same as cancellation).
+2. Re-check FreeBusy for the new time window (race protection).
+3. Update the Google Calendar event with new start/end times via `PATCH /calendar/v3/calendars/{calendarId}/events/{eventId}`.
+4. Update the Appointment record with new times.
+5. Send SMS notification about the reschedule.
+6. Remove old reminder jobs, schedule new ones for the updated time.
+
+### 4.3 Listing Reservations (`list_reservations`)
+
+Returns all upcoming appointments for the current patient (matched by `patient_phone`). Queries Google Calendar Events API filtering by `extendedProperties.private.patient_phone` and `extendedProperties.private.source = 'portal-asistan'`, with `timeMin = now()`.
+
+---
+
+## 5. Appointment Reminders (BullMQ)
+
+Reminders are the primary defense against no-shows. They are configurable per clinic and managed entirely through BullMQ delayed jobs.
+
+### 5.1 Configuration
+
+Stored in the clinic settings JSONB under `google_calendar.reminders`:
+
+```typescript
+reminders: {
+  enabled: boolean;                           // default true
+  channels: ('whatsapp' | 'sms')[];          // default ['whatsapp']
+  schedule: Array<{
+    hours_before: number;                     // e.g., 24, 2
+    message_template: string;                 // "Merhaba {{patient_name}}, ..."
+  }>;
+}
+```
+
+**Default schedule:** 24 hours before and 2 hours before the appointment.
+
+### 5.2 Scheduling Reminders on Booking
+
+When an appointment is created, the system schedules one BullMQ delayed job per reminder entry:
+
+```
+For each reminder in clinic.reminders.schedule:
+  delay = appointmentStartTime - (hours_before * 3600000) - Date.now()
+  if delay > 0:
+    queue.add('appointment:reminder', {
+      appointmentId, clinicId, tenantId,
+      patientPhone, patientName, startTime,
+      template: reminder.message_template,
+      channels: reminders.channels,
+    }, {
+      delay: delay,
+      jobId: "reminder:{appointmentId}:{hours_before}h",
+    })
+```
+
+The `jobId` pattern ensures idempotency -- re-scheduling the same reminder replaces rather than duplicates.
+
+### 5.3 Reminder Processor
+
+When the delayed job fires, the processor:
+
+1. Verify the appointment still exists and is not cancelled.
+2. Render the message template (replace `{{patient_name}}`, `{{time}}`, `{{date}}`, `{{clinic_name}}`).
+3. For each channel in `channels`:
+   - `whatsapp`: Send via BridgeService (Meta Business template message or Baileys direct message).
+   - `sms`: Send via NetGSM.
+
+### 5.4 Job Lifecycle on Mutations
+
+| Event | Action on Reminder Jobs |
+|-------|------------------------|
+| Appointment created | Schedule new jobs |
+| Appointment cancelled | Remove all jobs with `jobId` matching `reminder:{appointmentId}:*` |
+| Appointment rescheduled | Remove old jobs, schedule new jobs with updated times |
+
+---
+
+## 6. Appointment Validation (Batch Outbound Calls)
+
+Appointment validation is a purpose-built system for confirming existing appointments via outbound phone calls. Clinics upload a list of upcoming appointments, and the AI calls each patient to confirm, cancel, or reschedule.
+
+### 6.1 Data Model
+
+**appointment_validation_batches:**
+
+```
+appointment_validation_batches
+  batch_id              UUID PK
+  batch_tenant_id       UUID FK -> tenants
+  batch_clinic_id       UUID? FK -> clinics
+  batch_created_by_id   UUID FK -> users
+  batch_name            String
+  batch_status          enum: draft | submitted | in_progress | completed | cancelled
+  batch_el_batch_id     String?          -- ElevenLabs batch call ID
+  batch_agent_id        UUID? FK -> agents
+  batch_phone_id        UUID? FK -> phone_numbers (outbound phone)
+  batch_column_mapping  JSONB            -- {patient_name, patient_phone, appointment_date, ...}
+  batch_call_schedule   JSONB            -- {call_date, call_start_time, call_end_time, max_concurrent}
+  batch_stats           JSONB            -- {total, pending, calling, completed, ...}
+  batch_created_at      DateTime
+  batch_updated_at      DateTime
+```
+
+**appointment_validation_entries:**
+
+```
+appointment_validation_entries
+  bentry_id                  UUID PK
+  bentry_batch_id            UUID FK -> appointment_validation_batches (CASCADE)
+  bentry_row_index           Int
+  bentry_external_id         String
+  bentry_patient_name        String
+  bentry_patient_phone       String
+  bentry_appointment_date    String
+  bentry_appointment_time    String
+  bentry_doctor_name         String
+  bentry_department          String
+  bentry_notes               String
+  bentry_raw_data            JSONB            -- Original row data
+  bentry_call_status         enum: pending | calling | completed | failed | no_answer | voicemail
+  bentry_attempts            Int default 0
+  bentry_conversation_id     String?          -- ElevenLabs conversation ID
+  bentry_validation_result   enum: confirmed | cancelled | reschedule | unresolved (nullable)
+  bentry_reschedule_request  String?
+  bentry_patient_message     String?
+  bentry_call_duration_secs  Int default 0
+  bentry_called_at           DateTime?
+  bentry_result_at           DateTime?
+  bentry_created_at          DateTime
+  bentry_updated_at          DateTime
+```
+
+### 6.2 Validation Batch Flow
+
+```
+Clinic Admin                Frontend                  API                     BullMQ                ElevenLabs
+    |                          |                       |                        |                       |
+    |  Upload CSV/Excel        |                       |                        |                       |
+    |------------------------->|                       |                        |                       |
+    |                          |  Parse file (xlsx)    |                        |                       |
+    |                          |  Map columns          |                        |                       |
+    |                          |  Review entries        |                        |                       |
+    |                          |                       |                        |                       |
+    |  Confirm                 |                       |                        |                       |
+    |------------------------->|                       |                        |                       |
+    |                          |  POST /appointment-   |                        |                       |
+    |                          |  validation            |                        |                       |
+    |                          |---------------------->|                        |                       |
+    |                          |                       |  Create batch (draft)  |                       |
+    |                          |                       |  Create entries        |                       |
+    |                          |  batch created        |                        |                       |
+    |                          |<----------------------|                        |                       |
+    |                          |                       |                        |                       |
+    |  Submit batch            |                       |                        |                       |
+    |------------------------->|                       |                        |                       |
+    |                          |  POST /:id/submit     |                        |                       |
+    |                          |---------------------->|                        |                       |
+    |                          |                       |  1. Resolve agent      |                       |
+    |                          |                       |  2. Resolve phone      |                       |
+    |                          |                       |  3. batch -> submitted |                       |
+    |                          |                       |                        |                       |
+    |                          |                       |  Dispatch calls ------>|                       |
+    |                          |                       |                        |  For each entry:      |
+    |                          |                       |                        |  Check time window    |
+    |                          |                       |                        |  sipTrunkOutbound --->|
+    |                          |                       |                        |                       |  Call patient
+    |                          |                       |                        |                       |
+    |                          |                       |                        |                       |  AI: "Can you confirm
+    |                          |                       |                        |                       |   your appointment?"
+    |                          |                       |                        |                       |
+    |                          |                       |                        |                       |  Patient: "Yes, confirmed"
+    |                          |                       |                        |                       |
+    |                          |                       |                        |                       |  AI calls tool:
+    |                          |                       |                        |                       |  confirm_appointment_
+    |                          |                       |                        |                       |  validation({
+    |                          |                       |                        |                       |    result: "confirmed"
+    |                          |                       |                        |                       |  })
+    |                          |                       |                        |                       |
+    |                          |                       |  Webhook: tool result  |                       |
+    |                          |                       |<----------------------------------------------|
+    |                          |                       |  Update entry:         |                       |
+    |                          |                       |  validation_result =   |                       |
+    |                          |                       |  confirmed             |                       |
+    |                          |                       |                        |                       |
+    |                          |                       |  Post-call webhook     |                       |
+    |                          |                       |<----------------------------------------------|
+    |                          |                       |  Update entry:         |                       |
+    |                          |                       |  call_status,          |                       |
+    |                          |                       |  duration, conv_id     |                       |
+    |                          |                       |                        |                       |
+    |                          |                       |  Background sync       |                       |
+    |                          |                       |  (every 60s)           |                       |
+    |                          |                       |<---------------------->|                       |
+    |                          |                       |  Poll getBatchCall()   |                       |
+    |                          |                       |  Sync conversation_ids |                       |
+    |                          |                       |  Infer unresolved      |                       |
+    |                          |                       |                        |                       |
+    |                          |                       |  All entries done -->  |                       |
+    |                          |                       |  batch -> completed    |                       |
+    |                          |                       |                        |                       |
+    |  Export CSV              |                       |                        |                       |
+    |------------------------->|                       |                        |                       |
+    |                          |  GET /:id/export      |                        |                       |
+    |                          |---------------------->|                        |                       |
+    |                          |  CSV file             |                        |                       |
+    |                          |<----------------------|                        |                       |
+```
+
+### 6.3 Batch Lifecycle
+
+| State | Description | Allowed Transitions |
+|-------|-------------|-------------------|
+| `draft` | Batch created, entries uploaded. Editable. | submitted, (delete) |
+| `submitted` | Calls being dispatched. Not editable. | in_progress, cancelled |
+| `in_progress` | Calls actively running. | completed, cancelled |
+| `completed` | All entries processed. | -- |
+| `cancelled` | Manually cancelled. Pending calls aborted. | -- |
+
+### 6.4 Call Dispatch (BullMQ)
+
+Queue: `appointment-validation:dispatch`, concurrency: 3.
+
+For each entry in the batch:
+1. Check if within the configured time window (`batch_call_schedule.call_start_time` to `call_end_time`). If outside, delay the job until the window opens.
+2. Set `bentry_call_status = 'calling'`, `bentry_attempts += 1`.
+3. Call `elevenlabsService.sipTrunkOutboundCall()` with the patient phone, agent ID, and dynamic variables (patient name, appointment date/time, doctor name).
+4. On success, record `bentry_conversation_id`.
+5. On failure, mark `bentry_call_status = 'failed'`. If `attempts < max_attempts`, requeue with delay.
+
+### 6.5 During the Call: `confirm_appointment_validation` Tool
+
+The AI agent has a webhook tool registered at `POST /webhooks/elevenlabs/tools/confirm_appointment_validation`. When the patient gives a response, the AI calls this tool with:
+
+```json
+{
+  "result": "confirmed",           // confirmed | cancelled | reschedule
+  "reschedule_request": "...",     // Free text if rescheduling
+  "patient_message": "..."         // Patient's exact words
+}
+```
+
+The webhook handler:
+1. Resolves the tenant from `agent_id` header.
+2. Finds the entry by `conversation_id`.
+3. Updates `bentry_validation_result`, `bentry_reschedule_request`, `bentry_patient_message`, `bentry_result_at`.
+4. Recalculates `batch_stats`.
+
+### 6.6 Background Sync
+
+Queue: `appointment-validation:sync`, repeatable every 60 seconds.
+
+For each batch in `submitted` or `in_progress` status:
+1. Call `elevenlabsService.getBatchCall(batch_el_batch_id)` to get current call statuses.
+2. For entries missing `conversation_id`, match by phone number from the batch call response.
+3. For completed calls where the tool did not fire (patient hung up, call failed), infer `validation_result = 'unresolved'`.
+4. Update entry statuses and durations.
+5. If all entries are processed, transition batch to `completed`.
+
+### 6.7 CSV Export
+
+`GET /appointment-validation/:id/export` generates a CSV with columns:
+
+```
+Row, Patient Name, Patient Phone, Appointment Date, Appointment Time, Doctor,
+Department, Call Status, Validation Result, Reschedule Request, Patient Message,
+Call Duration, Called At, Result At
+```
+
+### 6.8 Validation Outcomes
+
+| Result | Meaning | Follow-up |
+|--------|---------|-----------|
+| `confirmed` | Patient confirmed attendance | No action needed |
+| `cancelled` | Patient wants to cancel | Clinic should free the slot |
+| `reschedule` | Patient wants a different time | `reschedule_request` contains details |
+| `unresolved` | No clear answer or call failed | May need manual follow-up or retry |
+
+---
+
+## 7. Data Model Summary
+
+### appointments
+
+```
+appointments
+  appt_id                     UUID PK
+  appt_tenant_id              UUID FK -> tenants
+  appt_clinic_id              UUID FK -> clinics (REQUIRED)
+  appt_patient_id             UUID FK -> patients (REQUIRED)
+  appt_doctor_id              UUID? FK -> users (doctor performing the treatment)
+  appt_treatment_id           UUID? FK -> treatments (what treatment this is for)
+  appt_treatment_plan_item_id UUID? FK -> treatment_plan_items (which plan item, if part of a plan)
+  appt_chat_id                UUID? FK -> whatsapp_chats
+  appt_session_id             UUID? FK -> whatsapp_sessions
+  appt_google_event_id        String
+  appt_patient_name           String
+  appt_patient_phone          String
+  appt_start_time             DateTime
+  appt_end_time               DateTime
+  appt_duration_minutes       Int
+  appt_type                   enum: appointment | walk_in | follow_up | consultation
+  appt_notes                  String
+  appt_status                 enum: scheduled | confirmed | in_progress | completed | cancelled | no_show
+  appt_source                 enum: whatsapp | voice_call | dashboard | walk_in
+  appt_conversation_id        String?           -- ElevenLabs conversation ID
+  appt_cancelled_at           DateTime?
+  appt_created_at             DateTime
+  appt_updated_at             DateTime
+
+  Indexes:
+    (appt_tenant_id, appt_start_time)
+    (appt_clinic_id, appt_start_time)
+    (appt_tenant_id, appt_status)
+    (appt_tenant_id, appt_patient_phone)
+    (appt_patient_id, appt_start_time)      -- patient appointment history
+    (appt_doctor_id, appt_start_time)       -- doctor's schedule
+  Unique:
+    (appt_google_event_id, appt_tenant_id)
+
+  Relations:
+    belongs_to patients via appt_patient_id
+    belongs_to users (doctor) via appt_doctor_id
+    belongs_to treatments via appt_treatment_id
+    belongs_to treatment_plan_items via appt_treatment_plan_item_id
+```
+
+**Status workflow:**
+
+| Status | Meaning | Transitions to |
+|--------|---------|---------------|
+| `scheduled` | Booked, upcoming | confirmed, cancelled, no_show |
+| `confirmed` | Patient confirmed (via validation call or manual) | in_progress, cancelled, no_show |
+| `in_progress` | Patient is currently being seen | completed |
+| `completed` | Visit finished | -- |
+| `cancelled` | Cancelled before visit | -- |
+| `no_show` | Patient did not show up | -- |
+
+**Source values:**
+
+| Source | When used |
+|--------|-----------|
+| `whatsapp` | Booked via WhatsApp AI |
+| `voice_call` | Booked during a phone call |
+| `dashboard` | Manually booked by staff from the dashboard |
+| `walk_in` | Walk-in patient registered at reception |
+
+**Type values:**
+
+| Type | Meaning |
+|------|---------|
+| `appointment` | Standard scheduled appointment |
+| `walk_in` | Walk-in visit (registered at reception) |
+| `follow_up` | Follow-up visit for a previous treatment |
+| `consultation` | Initial consultation / evaluation |
+
+**Design decisions:**
+- `appt_clinic_id` is required (not nullable) because every appointment belongs to a specific clinic's calendar.
+- `appt_patient_id` is required -- every appointment belongs to a patient. For AI-booked appointments, the patient is resolved from `ToolContext.patientPhone` via a Patient lookup (or auto-created).
+- `appt_doctor_id` links to a user with the doctor role. Nullable because not all appointments require a specific doctor at booking time.
+- `appt_treatment_id` links to the treatment catalog. Allows the system to use the treatment's `duration_minutes` for slot calculation.
+- `appt_treatment_plan_item_id` links to a specific item in a patient's treatment plan, enabling plan-to-appointment tracking.
+- `appt_chat_id` and `appt_session_id` are nullable because voice call and dashboard appointments have no WhatsApp chat context.
+- `appt_google_event_id` combined with `appt_tenant_id` is unique to prevent duplicate bookings.
+- `appt_patient_name` and `appt_patient_phone` are kept as denormalized fields for display and backward compatibility, even though the canonical source is now the `patients` table via `appt_patient_id`.
+
+### BullMQ Queues
+
+| Queue | Purpose | Concurrency |
+|-------|---------|-------------|
+| `appointment:reminder` | Send pre-appointment reminders | 5 |
+| `appointment-validation:dispatch` | Dispatch batch validation calls | 3 |
+| `appointment-validation:sync` | Sync statuses from ElevenLabs | 1 |
+
+### API Endpoints
+
+**Calendar management:**
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/whatsapp/google-calendar/auth-url` | `calendar:manage` | Get Google OAuth URL |
+| POST | `/whatsapp/google-calendar/disconnect` | `calendar:manage` | Disconnect calendar |
+| GET | `/whatsapp/google-calendar/calendars` | `calendar:read` | List available calendars |
+| PUT | `/whatsapp/google-calendar/calendar` | `calendar:manage` | Select active calendar |
+
+**Appointments:**
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/whatsapp/appointments` | `appointments:read` | List (paginated, filterable) |
+| GET | `/whatsapp/appointments/:id` | `appointments:read` | Detail |
+| GET | `/whatsapp/appointments/stats` | `appointments:read` | Aggregate statistics |
+| POST | `/appointments` | `appointments:manage` | Create appointment manually |
+| PUT | `/appointments/:id` | `appointments:manage` | Update appointment (reschedule, change doctor) |
+| PUT | `/appointments/:id/status` | `appointments:manage` | Update status (confirm, start, complete, no-show) |
+
+**Appointment validation:**
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/appointment-validation` | `validation:read` | List batches |
+| POST | `/appointment-validation` | `validation:manage` | Create batch with entries |
+| GET | `/appointment-validation/:id` | `validation:read` | Batch detail with stats |
+| POST | `/appointment-validation/:id/submit` | `validation:manage` | Submit for calling |
+| POST | `/appointment-validation/:id/cancel` | `validation:manage` | Cancel batch |
+| POST | `/appointment-validation/:id/retry` | `validation:manage` | Retry failed entries |
+| POST | `/appointment-validation/:id/entries/:entryId/retry` | `validation:manage` | Retry single entry |
+| GET | `/appointment-validation/:id/export` | `validation:export` | CSV export |
+| POST | `/appointment-validation/:id/sync` | `validation:manage` | Manual sync from ElevenLabs |
+
+### Feature Flags
+
+| Flag | Gates |
+|------|-------|
+| `google_calendar` | All calendar tools (`check_availability`, `reserve_slot`, `list_reservations`, `cancel_reservation`, `reschedule_reservation`) |
+| `appointment_validation` | All `/appointment-validation/*` endpoints and `confirm_appointment_validation` tool |
+
+---
+
+## 8. Doctor Profiles
+
+Each user with the `doctor` role has a corresponding `DoctorProfile` record that defines their availability and calendar preferences.
+
+### 8.1 Data Model
+
+```prisma
+model DoctorProfile {
+  profile_id                  String   @id @default(uuid())
+  profile_user_id             String   @unique
+  profile_specialty           String   @default("")
+  profile_title               String   @default("")  // "Dr.", "Prof. Dr."
+  profile_bio                 String   @default("")
+  profile_working_hours       Json     @default("[]")  // [{day, start, end}]
+  profile_appointment_duration Int     @default(30)
+  profile_color               String   @default("")  // Calendar display color
+  profile_is_accepting        Boolean  @default(true)
+  profile_created_at          DateTime @default(now())
+  profile_updated_at          DateTime @updatedAt
+
+  user User @relation(fields: [profile_user_id], references: [user_id], onDelete: Cascade)
+
+  @@map("doctor_profiles")
+}
+```
+
+**Key points:**
+- 1:1 with `users` (doctor role) via `profile_user_id UNIQUE`. Created automatically when a user with the doctor role is added.
+- `profile_working_hours` defines when this doctor is available for appointments, using the same format as clinic working hours: `[{day: 1, start: "09:00", end: "18:00"}, ...]` where `day` is 0=Sunday through 6=Saturday.
+- `profile_appointment_duration` is the default slot duration for this doctor (in minutes). Overrides the clinic default (`calcn_appointment_duration`) when this doctor is selected for a booking.
+- `profile_color` is a hex color code for the calendar UI -- each doctor gets a different color for visual distinction in the schedule view.
+- `profile_is_accepting` controls whether this doctor appears in available doctor lists. Set to `false` when the doctor is on leave or not taking new appointments.
+
+---
+
+## 9. Manual Booking from Dashboard
+
+Staff can book, update, and manage appointments directly from the dashboard without going through the AI flow.
+
+### 9.1 API Endpoints
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| POST | `/appointments` | `appointments:manage` | Create appointment manually (patient, doctor, treatment, time) |
+| PUT | `/appointments/:id` | `appointments:manage` | Update appointment (reschedule, change doctor, update status) |
+| PUT | `/appointments/:id/status` | `appointments:manage` | Update status (confirm, start, complete, no-show) |
+
+### 9.2 Manual Booking Flow
+
+```
+Staff member opens Appointments page
+  |
+  v
+1. Select patient
+  |  Search by name or phone number
+  |  Or create a new patient inline
+  |
+  v
+2. Select treatment (from catalog)
+  |  Treatment selection determines slot duration (if treatment.duration_minutes is set)
+  |
+  v
+3. Select doctor (optional)
+  |  List shows doctors with profile_is_accepting = true
+  |  Doctor selection narrows available slots to doctor's working hours
+  |
+  v
+4. System shows available slots
+  |  Uses the same availability algorithm as Section 2
+  |  Considers doctor's profile_working_hours (if selected)
+  |  Considers treatment duration (if selected)
+  |  Checks Google Calendar FreeBusy for conflicts
+  |
+  v
+5. Staff selects slot and confirms
+  |
+  v
+6. System creates:
+  |  a. Google Calendar event (with extendedProperties)
+  |  b. Appointment record in DB (appt_source = 'dashboard')
+  |  c. Schedules BullMQ reminder jobs
+```
+
+### 9.3 Status Transitions (Manual)
+
+Staff can manually transition appointment statuses via `PUT /appointments/:id/status`:
+
+```
+scheduled ──> confirmed ──> in_progress ──> completed
+    |              |
+    |              +──> cancelled
+    |              +──> no_show
+    +──> cancelled
+    +──> no_show
+```
+
+The status update endpoint enforces valid transitions and records the transition timestamp.
+
+---
+
+## 10. AI Client Tools
+
+The appointment system exposes the following tools through the generalized tool registry (see `src/tools/handlers/calendar.tools.ts` and `src/tools/handlers/validation.tools.ts`):
+
+| Tool | Parameters | Channels | Feature |
+|------|-----------|----------|---------|
+| `check_availability` | `{date, doctor_name?, treatment_name?}` | all | `google_calendar` |
+| `reserve_slot` | `{patient_name?, iso_start, iso_end, notes?, doctor_name?}` | all | `google_calendar` |
+| `list_reservations` | -- | all | `google_calendar` |
+| `cancel_reservation` | `{event_id}` | all | `google_calendar` |
+| `reschedule_reservation` | `{old_event_id, new_iso_start, new_iso_end, notes?}` | all | `google_calendar` |
+| `confirm_appointment_validation` | `{result, reschedule_request?, patient_message?}` | voice_call | `appointment_validation` |
+
+All tools receive a `ToolContext` with tenant, clinic, patient phone, and channel metadata. All results are logged in the `tool_execution_logs` table.
+
+**Patient linking:** `reserve_slot` resolves the patient from `ToolContext.patientPhone` by looking up the `patients` table. If a matching patient exists, `appt_patient_id` is set. If no patient is found, one is auto-created from the available context (phone, name).
+
+**Doctor filtering:** When `doctor_name` is provided to `check_availability`, the system looks up the matching `DoctorProfile` and uses the doctor's `profile_working_hours` and `profile_appointment_duration` for slot generation. When `doctor_name` is provided to `reserve_slot`, the created appointment is linked via `appt_doctor_id`.
+
+**Treatment filtering:** When `treatment_name` is provided to `check_availability`, the system looks up the matching treatment and uses `treatment.duration_minutes` for slot calculation (highest priority in the duration chain).