elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/03-MULTI-CLINIC.md

@@ -0,0 +1,742 @@
+# 03 — Multi-Clinic & Multi-Phone Architecture
+
+> Last updated: 2026-04-02
+
+> Covers the Clinic model, PhoneNumber model, clinic connections (Calendar, Meta),
+> phone-to-clinic-to-agent routing, and per-clinic self-contained configuration.
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Clinic Model](#2-clinic-model)
+3. [PhoneNumber Model](#3-phonenumber-model)
+4. [Clinic Connections](#4-clinic-connections)
+5. [Routing Flow](#5-routing-flow)
+6. [Clinic Configuration](#6-clinic-configuration)
+7. [Examples](#7-examples)
+
+---
+
+## 1. Overview
+
+The system supports two operating modes through the same data model:
+
+- **Single-clinic tenants** -- one tenant, one clinic (auto-created on registration as the default clinic). Everything works transparently with no clinic selection required. This is the common case for a solo practice.
+- **Multi-clinic tenants** -- one tenant, many clinics (branches/locations). Each clinic has its own phone numbers, calendar, operator, and agent configuration. Incoming messages and calls are routed to the correct clinic based on which phone number the patient contacted.
+
+The architecture uses two layers:
+
+```
+Tenant (1)
+  |
+  +-- Clinic (1..N)
+        |
+        +-- PhoneNumber (0..N)    -- WhatsApp, inbound calls, outbound calls
+        +-- Agent (0..N)           -- ElevenLabs AI agents
+        +-- CalendarConnection (0..1)
+        +-- ClinicMetaConnections (0..N)  -- multiple WhatsApp/Instagram connections
+        +-- Users (via assignment)
+        +-- Patients (0..N)
+        +-- Treatments (0..N)
+```
+
+Each clinic is **self-contained** -- it owns all its operational configuration directly (language, AI provider, grace period, operator settings, SMS, notifications). There is no settings inheritance chain from tenant to clinic.
+
+---
+
+## 2. Clinic Model
+
+### Prisma Schema
+
+```prisma
+model Clinic {
+  clinic_id          String   @id @default(uuid())
+  clinic_tenant_id   String
+  clinic_name        String
+  clinic_slug        String   // URL-friendly: "kadikoy", "main"
+  clinic_address     String   @default("")
+  clinic_timezone    String   @default("Europe/Istanbul")
+  clinic_is_default  Boolean  @default(false)
+  clinic_is_active   Boolean  @default(true)
+
+  // Language & AI (self-contained -- no tenant fallback)
+  clinic_language                   String   @default("tr")
+  clinic_ai_provider                String   @default("elevenlabs")
+  clinic_ai_model                   String   @default("")
+
+  // Operator workflow (proper columns -- queried on every incoming message)
+  clinic_operator_phone            String?  // Doctor's WhatsApp number for this clinic
+  clinic_operator_prefix           String   @default("R")  // REF code prefix
+  clinic_operator_timeout_hours    Int      @default(24)    // hours before request expires
+  clinic_grace_period_seconds      Int      @default(180)   // seconds before AI takes over
+
+  // AI shift (proper columns)
+  clinic_ai_shift_enabled          Boolean  @default(false)
+  clinic_ai_shift_schedule         Json     @default("[]")  // [{day, start, end}]
+
+  // Messaging
+  clinic_blacklisted_numbers       String[] @default([])
+  clinic_fixed_first_message       String?  // null = disabled
+
+  // SMS & notifications
+  clinic_sms_enabled               Boolean  @default(false)
+  clinic_sms_phones                String[] @default([])
+  clinic_notification_phones       String[] @default([])
+
+  // Message retention
+  clinic_message_retention_days    Int      @default(7)     // auto-deletion via BullMQ job
+
+  clinic_created_at  DateTime @default(now())
+  clinic_updated_at  DateTime @updatedAt
+
+  tenant              Tenant                 @relation(fields: [clinic_tenant_id], references: [tenant_id], onDelete: Cascade)
+  userAssignments     UserClinicAssignment[]
+  agents              Agent[]
+  phoneNumbers        PhoneNumber[]
+  calendarConnection  ClinicCalendarConnection?
+  metaConnections     ClinicMetaConnection[]   // 1:many -- multiple WhatsApp/Instagram connections
+  whatsappChats       WhatsAppChat[]
+  whatsappSessions    WhatsAppSession[]
+  appointments        Appointment[]
+  operatorRequests    OperatorRequest[]
+  calls               Call[]
+  leads               Lead[]
+  outboundCampaigns   OutboundCampaign[]
+  validationBatches   AppointmentValidationBatch[]
+  patients            Patient[]
+  treatments          Treatment[]
+
+  @@unique([clinic_tenant_id, clinic_slug])
+  @@index([clinic_tenant_id])
+  @@index([clinic_tenant_id, clinic_operator_phone])
+  @@map("clinics")
+}
+```
+
+### Key Design Decisions
+
+**Default clinic:** Every tenant gets exactly one clinic with `clinic_is_default = true` on registration. Single-clinic tenants never need to create or manage clinics -- the default clinic is used implicitly. Multi-clinic tenants can create additional clinics and optionally change which one is the default.
+
+**All operational config is on proper columns:** There is no `clinic_settings` JSONB blob. Every configurable value is a typed column with a sensible default. This means no null-means-inherit pattern and no runtime resolution logic -- the clinic row is the single source of truth.
+
+| Column | Reason |
+|--------|--------|
+| `clinic_operator_phone` | Queried on every incoming message (WHERE clause) |
+| `clinic_operator_prefix` | Queried for REF code generation |
+| `clinic_operator_timeout_hours` | Queried for expiry sweep |
+| `clinic_grace_period_seconds` | Queried on every session start |
+| `clinic_ai_shift_enabled`, `clinic_ai_shift_schedule` | Queried by schedule sync job |
+| `clinic_blacklisted_numbers` | Queried on every incoming message |
+| `clinic_fixed_first_message` | Queried on first message in session |
+| `clinic_language`, `clinic_ai_provider`, `clinic_ai_model` | Used when initializing AI connections |
+| `clinic_sms_enabled`, `clinic_sms_phones`, `clinic_notification_phones` | Queried by notification service |
+| `clinic_message_retention_days` | Used by BullMQ auto-deletion job |
+
+### Slug
+
+The `clinic_slug` is a URL-friendly identifier unique within a tenant (enforced by `@@unique([clinic_tenant_id, clinic_slug])`). Used in URLs and webhook routing. Examples: `"main"`, `"kadikoy"`, `"besiktas"`.
+
+---
+
+## 3. PhoneNumber Model
+
+### Purpose
+
+The `PhoneNumber` table is a **unified registry** for all phone numbers across all use cases. It replaces four scattered locations in the current system:
+
+| Old Location | Now In |
+|-------------|--------|
+| `tenant.settings.whatsapp_agent.connected_phone` | `phone_numbers` with `purpose = whatsapp` |
+| `InboundCallConfig.phone_number` | `phone_numbers` with `purpose = inbound_call` |
+| `tenant.settings.outbound_call_phone_number_id` | `phone_numbers` with `purpose = outbound_call` |
+| Per-clinic operator phones | `clinic.clinic_operator_phone` (separate -- this is the *doctor's* personal number, not a system phone) |
+
+### Prisma Schema
+
+```prisma
+model PhoneNumber {
+  phone_id                    String               @id @default(uuid())
+  phone_tenant_id             String
+  phone_clinic_id             String?              // null = tenant-level (unassigned)
+  phone_number                String               // E.164: +905551234567
+  phone_label                 String               @default("")
+  phone_purpose               PhoneNumberPurpose   // whatsapp | inbound_call | outbound_call
+  phone_provider              PhoneNumberProvider   // meta_business | elevenlabs
+  phone_external_account_id   String?              // Meta phone_number_id
+  phone_elevenlabs_phone_id   String?              // ElevenLabs phone number ID
+  phone_elevenlabs_agent_id   String?              // ElevenLabs agent ID (external)
+  phone_agent_id              String?              // FK to agents table (internal routing)
+  phone_wa_connected          Boolean              @default(false)
+  phone_wa_connected_at       DateTime?
+  phone_wa_bridge_provider    String?              // reserved for future use
+  phone_schedule_enabled      Boolean              @default(false)
+  phone_schedule              Json                 @default("[]")  // [{day, start, end}]
+  phone_agent_assigned        Boolean              @default(false)
+  phone_is_active             Boolean              @default(true)
+  phone_created_at            DateTime             @default(now())
+  phone_updated_at            DateTime             @updatedAt
+
+  tenant Tenant  @relation(fields: [phone_tenant_id], references: [tenant_id], onDelete: Cascade)
+  clinic Clinic? @relation(fields: [phone_clinic_id], references: [clinic_id])
+  agent  Agent?  @relation(fields: [phone_agent_id], references: [agent_id])
+  chats             WhatsAppChat[]
+  campaigns         OutboundCampaign[]
+  validationBatches AppointmentValidationBatch[]
+
+  @@unique([phone_tenant_id, phone_number, phone_purpose])
+  @@index([phone_tenant_id, phone_purpose])
+  @@index([phone_clinic_id])
+  @@index([phone_provider, phone_external_account_id])
+  @@map("phone_numbers")
+}
+```
+
+### Enums
+
+```prisma
+enum PhoneNumberPurpose {
+  whatsapp        // WhatsApp AI chat
+  inbound_call    // Receive voice calls via ElevenLabs SIP trunk
+  outbound_call   // Make voice calls (campaigns, appointment validation)
+}
+
+enum PhoneNumberProvider {
+  meta_business   // Official Meta Business Cloud API
+  elevenlabs      // ElevenLabs SIP trunk (voice calls)
+}
+```
+
+### Key Concepts
+
+**One number, one purpose:** The same E.164 number can appear multiple times in the table with different purposes. For example, `+905551234567` might be both a `whatsapp` number (for AI chat) and an `inbound_call` number (for voice). The uniqueness constraint is `(tenant_id, number, purpose)`.
+
+**Provider determines how the number connects:**
+
+| Purpose | Provider | How It Works |
+|---------|----------|-------------|
+| `whatsapp` | `meta_business` | Official WhatsApp Business API via Meta. OAuth-based setup. |
+| `inbound_call` | `elevenlabs` | ElevenLabs SIP trunk. Phone is registered with ElevenLabs, agent assigned via API. |
+| `outbound_call` | `elevenlabs` | Same ElevenLabs SIP trunk. Used for outbound campaigns and appointment validation. |
+
+**Phone -> Clinic -> Agent routing chain:**
+A phone number is assigned to a clinic (`phone_clinic_id`). The phone number points to an agent (`phone_agent_id`). When a message arrives on a phone number, the system looks up the phone, gets the clinic, gets the agent, and routes accordingly.
+
+```
+Incoming message/call
+       |
+       v
+  PhoneNumber (lookup by phone_number + purpose)
+       |
+       +-- phone_clinic_id --> Clinic (settings, operator, calendar)
+       |
+       +-- phone_agent_id  --> Agent (AI config, voice, prompt)
+```
+
+**Unassigned phones:** A phone number with `phone_clinic_id = null` is tenant-level (not yet assigned to a clinic). It must be assigned before it can route messages.
+
+### Indexes
+
+| Index | Purpose |
+|-------|---------|
+| `(phone_tenant_id, phone_purpose)` | List all WhatsApp numbers for a tenant, all inbound numbers, etc. |
+| `(phone_clinic_id)` | Find all numbers for a clinic |
+| `(phone_provider, phone_external_account_id)` | Webhook routing: look up phone by Meta phone_number_id |
+| `(phone_tenant_id, phone_number, phone_purpose)` UNIQUE | Prevent duplicate registrations |
+
+### API Endpoints
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/phone-numbers` | `phone_numbers:read` | List all (filterable by purpose, clinic, provider) |
+| POST | `/phone-numbers` | `phone_numbers:manage` | Register phone number |
+| GET | `/phone-numbers/:id` | `phone_numbers:read` | Detail with status |
+| PUT | `/phone-numbers/:id` | `phone_numbers:manage` | Update config (label, clinic, agent, schedule) |
+| DELETE | `/phone-numbers/:id` | `phone_numbers:manage` | Remove phone number |
+| POST | `/phone-numbers/:id/connect-whatsapp` | `phone_numbers:manage` | Initiate WhatsApp connection |
+| POST | `/phone-numbers/:id/disconnect-whatsapp` | `phone_numbers:manage` | Disconnect WhatsApp |
+| GET | `/phone-numbers/:id/whatsapp-status` | `phone_numbers:read` | Connection status |
+| PUT | `/phone-numbers/:id/schedule` | `phone_numbers:manage` | Update inbound call schedule |
+| POST | `/phone-numbers/:id/toggle-agent` | `phone_numbers:manage` | Manual assign/unassign ElevenLabs agent |
+
+---
+
+## 4. Clinic Connections
+
+Clinic connections are **extracted from JSONB into dedicated tables** because they contain encrypted secrets and have distinct query/lifecycle patterns.
+
+### 4.1 ClinicCalendarConnection
+
+One Google Calendar OAuth connection per clinic. Stores encrypted refresh tokens for the Calendar API.
+
+```prisma
+model ClinicCalendarConnection {
+  calcn_id                      String    @id @default(uuid())
+  calcn_clinic_id               String    @unique  // 1:1 with Clinic
+  calcn_google_email            String?
+  calcn_encrypted_refresh_token String?   // AES-256-GCM encrypted
+  calcn_calendar_id             String?
+  calcn_calendar_name           String?
+  calcn_timezone                String    @default("Europe/Istanbul")
+  calcn_appointment_duration    Int       @default(30)  // minutes
+  calcn_working_hours           Json      @default("[]")  // [{day, start, end}]
+  calcn_blocked_dates           Json      @default("[]")  // [{date, reason}]
+  calcn_connected_at            DateTime?
+  calcn_created_at              DateTime  @default(now())
+  calcn_updated_at              DateTime  @updatedAt
+
+  clinic Clinic @relation(fields: [calcn_clinic_id], references: [clinic_id], onDelete: Cascade)
+
+  @@map("clinic_calendar_connections")
+}
+```
+
+**Why extracted from JSONB:**
+- Contains `calcn_encrypted_refresh_token` -- encrypted secrets should not live in a generic JSON blob. Dedicated columns allow explicit access control and audit.
+- Queried independently: token refresh logic, FreeBusy API calls, and appointment tools all need this data without loading the full clinic settings.
+- Lifecycle differs from clinic settings: connection/disconnection is a distinct operation with its own OAuth flow.
+
+### 4.2 ClinicMetaConnection
+
+Multiple Meta Business API connections per clinic. Each connection represents one WhatsApp phone number or Instagram page. A clinic can have several WhatsApp numbers and Instagram connections simultaneously.
+
+```prisma
+model ClinicMetaConnection {
+  meta_id                        String    @id @default(uuid())
+  meta_clinic_id                 String    // FK to clinics (1:many -- multiple connections per clinic)
+  meta_waba_id                   String?   // WhatsApp Business Account ID
+  meta_phone_number_id           String?
+  meta_display_phone             String?
+  meta_encrypted_access_token    String?   // AES-256-GCM encrypted
+  meta_instagram_connected       Boolean   @default(false)
+  meta_instagram_page_id         String?
+  meta_encrypted_page_token      String?   // AES-256-GCM encrypted
+  meta_connected_at              DateTime?
+  meta_created_at                DateTime  @default(now())
+  meta_updated_at                DateTime  @updatedAt
+
+  clinic Clinic @relation(fields: [meta_clinic_id], references: [clinic_id], onDelete: Cascade)
+
+  @@map("clinic_meta_connections")
+}
+```
+
+**Why extracted from JSONB:**
+- Two encrypted token fields (`meta_encrypted_access_token`, `meta_encrypted_page_token`).
+- Queried on every incoming Meta webhook to resolve the clinic.
+- Indexed by `meta_phone_number_id` for webhook routing (not shown in schema but critical for performance).
+- Connection/disconnection is a distinct OAuth flow with its own state.
+
+### Why Not Keep Secrets in JSONB?
+
+| Concern | JSONB column | Dedicated table |
+|---------|-------------|-----------------|
+| Encryption at field level | Must decrypt entire JSON, extract, re-encrypt on update | Encrypt/decrypt individual column |
+| Query pattern | `WHERE settings->>'encrypted_token' IS NOT NULL` is awkward | `WHERE encrypted_refresh_token IS NOT NULL` |
+| Audit trail | "settings changed" -- which field? | "calendar connection updated" -- clear |
+| Access control | Cannot grant column-level DB permissions | Can restrict table access |
+| Schema evolution | Add fields to JSON blob, hope nothing breaks | Add columns with proper migrations |
+
+---
+
+## 5. Routing Flow
+
+### 5.1 Incoming WhatsApp Message
+
+```
+WhatsApp message arrives at webhook
+       |
+       v
+  Extract sender phone number + recipient phone number
+       |
+       v
+  Lookup: phone_numbers WHERE phone_number = recipient
+                        AND   phone_purpose = 'whatsapp'
+                        AND   phone_wa_connected = true
+       |
+       v
+  Found PhoneNumber record
+       |
+       +-- phone_clinic_id --> Clinic
+       |     |
+       |     +-- clinic_operator_phone (for operator workflow)
+       |     +-- clinic_grace_period_seconds (self-contained, no fallback)
+       |     +-- clinic_blacklisted_numbers (check sender)
+       |     +-- calendarConnection (for appointment tools)
+       |
+       +-- phone_agent_id --> Agent
+       |     |
+       |     +-- agent_elevenlabs_id (for ElevenLabs WS connection)
+       |     +-- agent_system_prompt
+       |     +-- agent_language
+       |
+       +-- phone_tenant_id --> Tenant
+             |
+             +-- tenant_enabled_features (feature flags)
+```
+
+### 5.2 Incoming Voice Call
+
+```
+Inbound call arrives at ElevenLabs SIP trunk
+       |
+       v
+  ElevenLabs routes to configured agent (by phone_elevenlabs_agent_id)
+       |
+       v
+  Post-call webhook fires with agent_id
+       |
+       v
+  Lookup: agents WHERE agent_elevenlabs_id = webhook.agent_id
+       |
+       v
+  Agent --> Clinic (agent_clinic_id) --> Tenant (agent_tenant_id)
+       |
+       v
+  Process call record, trigger post-call actions
+```
+
+### 5.3 Single-Clinic vs Multi-Clinic Routing
+
+**Single-clinic tenant:**
+- One default clinic, one or two phone numbers.
+- Routing is trivial: every phone number points to the same clinic.
+- No clinic selection UI needed. The clinic is implicit.
+- All data (chats, calls, appointments) belongs to the single clinic.
+
+**Multi-clinic tenant:**
+- Multiple clinics, each with its own phone numbers.
+- Routing is phone-number-based: the patient's choice of which number to contact determines which clinic they reach.
+- Each clinic can have a different agent, different calendar, different operator.
+- The dashboard shows a clinic selector, and data is filtered by clinic.
+
+```
+Multi-clinic dental chain:
+
+  Tenant: "DentPlus"
+  |
+  +-- Clinic: "Kadikoy"
+  |     +-- Phone: +905551001 (whatsapp, meta_business) --> Agent: "DentPlus Kadikoy AI"
+  |     +-- Phone: +905551002 (inbound_call, elevenlabs) --> Agent: "DentPlus Kadikoy Voice"
+  |     +-- CalendarConnection: dentplus.kadikoy@gmail.com
+  |
+  +-- Clinic: "Besiktas"
+  |     +-- Phone: +905552001 (whatsapp, meta_business) --> Agent: "DentPlus Besiktas AI"
+  |     +-- Phone: +905552002 (inbound_call, elevenlabs) --> Agent: "DentPlus Besiktas Voice"
+  |     +-- CalendarConnection: dentplus.besiktas@gmail.com
+  |
+  +-- Clinic: "Atasehir"
+        +-- Phone: +905553001 (whatsapp, meta_business) --> Agent: "DentPlus Atasehir AI"
+        +-- CalendarConnection: dentplus.atasehir@gmail.com
+```
+
+Patient texts `+905551001` --> routed to Kadikoy clinic --> Kadikoy AI agent responds --> appointments booked on Kadikoy calendar.
+
+---
+
+## 6. Clinic Configuration
+
+Each clinic is **self-contained** -- every operational setting lives directly on the clinic row with a sensible default. There is no null-means-inherit pattern and no tenant-level fallback chain.
+
+### 6.1 Configuration Table
+
+| Setting | Column | Type | Default | Description |
+|---------|--------|------|---------|-------------|
+| Language | `clinic_language` | String | `"tr"` | AI and notification language |
+| AI provider | `clinic_ai_provider` | String | `"elevenlabs"` | AI service provider |
+| AI model | `clinic_ai_model` | String | `""` | Specific model override |
+| Grace period (seconds) | `clinic_grace_period_seconds` | Int | 180 | Time before AI takes over |
+| Operator phone | `clinic_operator_phone` | String? | null (disabled) | Doctor's WhatsApp number |
+| Operator REF prefix | `clinic_operator_prefix` | String | `"R"` | REF code prefix letter |
+| Operator timeout (hours) | `clinic_operator_timeout_hours` | Int | 24 | Hours before request expires |
+| AI shift | `clinic_ai_shift_enabled` + `clinic_ai_shift_schedule` | Bool + Json | disabled | Schedule windows |
+| Blacklisted numbers | `clinic_blacklisted_numbers` | String[] | [] | Numbers that bypass AI |
+| Fixed first message | `clinic_fixed_first_message` | String? | null (disabled) | Auto-greeting on new session |
+| SMS enabled | `clinic_sms_enabled` | Bool | false | Whether SMS notifications are active |
+| SMS phones | `clinic_sms_phones` | String[] | [] | Recipient numbers for SMS |
+| Notification phones | `clinic_notification_phones` | String[] | [] | Recipient numbers for push notifications |
+| Message retention (days) | `clinic_message_retention_days` | Int | 7 | Auto-deletion via BullMQ job |
+| Appointment duration (min) | `calcn_appointment_duration` | Int | 30 | On `ClinicCalendarConnection` |
+
+### 6.2 Reading Config
+
+```typescript
+// No resolution logic needed -- read directly from clinic
+const gracePeriod = clinic.clinic_grace_period_seconds;      // always has a value (default 180)
+const operatorPrefix = clinic.clinic_operator_prefix;        // always has a value (default "R")
+const operatorTimeout = clinic.clinic_operator_timeout_hours; // always has a value (default 24)
+const operatorPhone = clinic.clinic_operator_phone;          // null means operator workflow disabled
+const retentionDays = clinic.clinic_message_retention_days;  // always has a value (default 7)
+```
+
+No `resolveClinicSettings()` function is needed. The clinic row is the single source of truth.
+
+---
+
+## 7. Examples
+
+### Example 1: Single-Clinic Tenant (Solo Dental Practice)
+
+**Tenant:** "Dr. Ayse Yilmaz Dis Klinigi"
+
+```
+Tenant
+  tenant_id: "t-001"
+  tenant_name: "Dr. Ayse Yilmaz Dis Klinigi"
+  tenant_enabled_features: ["whatsapp_agent", "google_calendar", "operator_workflow"]
+
+Clinic (auto-created on registration)
+  clinic_id: "c-001"
+  clinic_tenant_id: "t-001"
+  clinic_name: "Dr. Ayse Yilmaz Dis Klinigi"
+  clinic_slug: "main"
+  clinic_is_default: true
+  clinic_language: "tr"
+  clinic_operator_phone: "+905559876543"  (Dr. Ayse's personal WhatsApp)
+  clinic_operator_prefix: "K"
+  clinic_operator_timeout_hours: 24
+  clinic_grace_period_seconds: 180
+  clinic_message_retention_days: 7
+
+PhoneNumber
+  phone_id: "p-001"
+  phone_tenant_id: "t-001"
+  phone_clinic_id: "c-001"
+  phone_number: "+905551112233"
+  phone_purpose: whatsapp
+  phone_provider: meta_business
+  phone_wa_connected: true
+  phone_agent_id: "a-001"
+
+Agent
+  agent_id: "a-001"
+  agent_tenant_id: "t-001"
+  agent_clinic_id: "c-001"
+  agent_elevenlabs_id: "el_abc123"
+  agent_name: "Ayse Klinik AI"
+  agent_language: "tr"
+
+ClinicCalendarConnection
+  calcn_clinic_id: "c-001"
+  calcn_google_email: "ayse.klinik@gmail.com"
+  calcn_encrypted_refresh_token: "AES256GCM:..."
+  calcn_calendar_id: "primary"
+  calcn_appointment_duration: 30
+  calcn_working_hours: [
+    {"day": 1, "start": "09:00", "end": "18:00"},
+    {"day": 2, "start": "09:00", "end": "18:00"},
+    {"day": 3, "start": "09:00", "end": "18:00"},
+    {"day": 4, "start": "09:00", "end": "18:00"},
+    {"day": 5, "start": "09:00", "end": "17:00"}
+  ]
+```
+
+**What happens when a patient texts +905551112233:**
+
+1. Meta webhook arrives. Lookup `phone_numbers` by `+905551112233` + `whatsapp`.
+2. Found: clinic = `c-001`, agent = `a-001`.
+3. Read settings directly from clinic: grace period = 180, operator prefix = "K".
+4. Check blacklist: `clinic_blacklisted_numbers` is empty.
+5. Route to Agent `a-001` (ElevenLabs ID `el_abc123`).
+6. AI responds. If patient sends photo, forward to operator phone `+905559876543`.
+7. If patient asks for appointment, AI checks `calcn_working_hours` and Google FreeBusy.
+
+The user (Dr. Ayse, role = `owner`) never sees a clinic selector in the UI. The single default clinic is implicit everywhere.
+
+---
+
+### Example 2: Multi-Clinic Dental Chain (3 Branches)
+
+**Tenant:** "DentPlus"
+
+```
+Tenant
+  tenant_id: "t-002"
+  tenant_name: "DentPlus"
+  tenant_enabled_features: [
+    "whatsapp_agent", "google_calendar", "operator_workflow",
+    "inbound_agent", "appointment_validation"
+  ]
+```
+
+#### Clinic 1: Kadikoy (default)
+
+```
+Clinic
+  clinic_id: "c-010"
+  clinic_name: "DentPlus Kadikoy"
+  clinic_slug: "kadikoy"
+  clinic_is_default: true
+  clinic_operator_phone: "+905551110001"    (Dr. Mehmet)
+  clinic_operator_prefix: "D"
+  clinic_operator_timeout_hours: 8
+  clinic_grace_period_seconds: 120
+  clinic_message_retention_days: 7
+
+PhoneNumbers:
+  +905550010001  purpose=whatsapp       provider=meta_business  agent="DentPlus Kadikoy Chat AI"
+  +905550010002  purpose=inbound_call   provider=elevenlabs     agent="DentPlus Kadikoy Voice AI"
+  +905550010003  purpose=outbound_call  provider=elevenlabs     agent="DentPlus Outbound"
+
+CalendarConnection:
+  google_email: dentplus.kadikoy@gmail.com
+  appointment_duration: 45
+  working_hours: Mon-Fri 09:00-19:00, Sat 10:00-14:00
+```
+
+#### Clinic 2: Besiktas
+
+```
+Clinic
+  clinic_id: "c-011"
+  clinic_name: "DentPlus Besiktas"
+  clinic_slug: "besiktas"
+  clinic_is_default: false
+  clinic_operator_phone: "+905551110002"    (Dr. Elif)
+  clinic_operator_prefix: "B"
+  clinic_operator_timeout_hours: 12
+  clinic_grace_period_seconds: 90
+  clinic_message_retention_days: 7
+
+PhoneNumbers:
+  +905550020001  purpose=whatsapp       provider=meta_business  agent="DentPlus Besiktas Chat AI"
+  +905550020002  purpose=inbound_call   provider=elevenlabs     agent="DentPlus Besiktas Voice AI"
+
+CalendarConnection:
+  google_email: dentplus.besiktas@gmail.com
+  appointment_duration: 30    (shorter appointments at this branch)
+  working_hours: Mon-Sat 08:00-20:00
+```
+
+#### Clinic 3: Atasehir
+
+```
+Clinic
+  clinic_id: "c-012"
+  clinic_name: "DentPlus Atasehir"
+  clinic_slug: "atasehir"
+  clinic_is_default: false
+  clinic_operator_phone: null              (no operator workflow -- AI only)
+  clinic_operator_prefix: "D"
+  clinic_operator_timeout_hours: 12
+  clinic_grace_period_seconds: 120
+  clinic_message_retention_days: 7
+
+PhoneNumbers:
+  +905550030001  purpose=whatsapp       provider=meta_business  agent="DentPlus Atasehir Chat AI"
+
+CalendarConnection:
+  google_email: dentplus.atasehir@gmail.com
+  appointment_duration: 45
+  working_hours: Mon-Fri 10:00-18:00
+```
+
+#### Users and Clinic Assignments
+
+```
+User: Ahmet (owner)
+  role: owner
+  --> sees ALL three clinics (no assignments needed)
+
+User: Zeynep (admin)
+  role: admin
+  assignments: [c-010 (Kadikoy), c-011 (Besiktas)]
+  --> sees Kadikoy + Besiktas data
+
+User: Dr. Mehmet (doctor)
+  role: doctor
+  assignments: [c-010 (Kadikoy)]
+  --> sees only Kadikoy patients, appointments, chats
+
+User: Fatma (receptionist)
+  role: receptionist
+  assignments: [c-011 (Besiktas), c-012 (Atasehir)]
+  --> sees Besiktas + Atasehir chats, appointments, leads
+```
+
+#### Settings Per Clinic
+
+| Setting | Kadikoy | Besiktas | Atasehir |
+|---------|---------|----------|----------|
+| Grace period (s) | 120 | 90 | 120 |
+| Operator prefix | "D" | "B" | "D" |
+| Operator timeout (h) | 8 | 12 | 12 |
+| Appt duration (min) | 45 (calendar) | 30 (calendar) | 45 (calendar) |
+| Operator phone | +905551110001 | +905551110002 | null (disabled) |
+| WhatsApp provider | Meta Business | Meta Business | Meta Business |
+| Message retention | 7 days | 7 days | 7 days |
+
+#### Routing in Action
+
+**Patient A texts +905550020001 (Besiktas WhatsApp):**
+- Lookup phone number --> Besiktas clinic (`c-011`)
+- Agent: "DentPlus Besiktas Chat AI"
+- Grace period: 90s (Besiktas override)
+- If patient sends photo: forward to Dr. Elif (+905551110002)
+- REF code prefix: "B" (Besiktas override) --> B0001
+- Appointment: booked on `dentplus.besiktas@gmail.com`, 30-minute slots
+
+**Patient B calls +905550010002 (Kadikoy inbound):**
+- ElevenLabs routes to "DentPlus Kadikoy Voice AI"
+- Post-call webhook: agent_elevenlabs_id --> Agent --> Clinic = Kadikoy
+- Call record stored with `call_clinic_id = c-010`
+- Lead generated with `lead_clinic_id = c-010`
+
+**Patient C texts +905550030001 (Atasehir WhatsApp):**
+- Lookup phone number --> Atasehir clinic (`c-012`)
+- Operator phone is null --> operator workflow disabled for this clinic
+- AI handles everything directly (no photo forwarding)
+
+---
+
+## Appendix: Agent Model
+
+Agents are not tied to a specific phone number or call direction. The same agent can serve WhatsApp chat, inbound calls, and outbound campaigns through different PhoneNumber records pointing to it.
+
+```prisma
+model Agent {
+  agent_id                String   @id @default(uuid())
+  agent_tenant_id         String
+  agent_clinic_id         String?  // null = tenant-level (shared across clinics)
+  agent_elevenlabs_id     String   // ElevenLabs agent ID
+  agent_name              String   @default("")
+  agent_description       String   @default("")
+
+  // Voice & language
+  agent_voice_id          String   @default("")
+  agent_language          String   @default("tr")
+  agent_greeting          String   @default("")
+
+  // AI config
+  agent_system_prompt     String   @default("")
+  agent_ai_provider       String?  // null = use clinic default
+  agent_ai_model          String?  // null = use clinic default
+
+  // Post-call processing
+  agent_post_call_strategy     PostCallStrategy @default(summarize)
+  agent_post_call_wa_notify    Boolean          @default(true)
+  agent_post_call_sms_notify   Boolean          @default(false)
+  agent_summary_prompt         String           @default("")
+  agent_wa_message_template    String           @default("")
+
+  agent_extra_config      Json     @default("{}")
+  agent_is_active         Boolean  @default(true)
+  agent_created_at        DateTime @default(now())
+  agent_updated_at        DateTime @updatedAt
+
+  tenant              Tenant       @relation(...)
+  clinic              Clinic?      @relation(...)
+  phoneNumbers        PhoneNumber[]
+  calls               Call[]
+  outboundCampaigns   OutboundCampaign[]
+  validationBatches   AppointmentValidationBatch[]
+
+  @@index([agent_tenant_id])
+  @@index([agent_clinic_id])
+  @@index([agent_elevenlabs_id])
+  @@map("agents")
+}
+```
+
+**Tenant-level agents** (`agent_clinic_id = null`) are shared across all clinics. Clinic-level agents are scoped to a specific clinic. A phone number references an agent via `phone_agent_id`; the agent's clinic assignment does not need to match the phone's clinic assignment (though it usually does).