elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/01-DATABASE-SCHEMA.md

@@ -0,0 +1,2564 @@
+# Database Schema Reference
+
+> Portal Asistan 7/24 -- Complete PostgreSQL schema documentation.
+> Every table, column, index, relation, and design decision.
+> Source: Prisma schema from NESTJS_MIGRATION_REFERENCE.md Section 6.2
+> Last updated: 2026-04-02
+
+---
+
+## Table of Contents
+
+1. [Naming Convention](#naming-convention)
+2. [Enums](#enums)
+3. [Table Definitions](#table-definitions)
+   - [tenants](#1-tenants)
+   - [clinics](#2-clinics)
+   - [clinic_calendar_connections](#3-clinic_calendar_connections)
+   - [clinic_meta_connections](#4-clinic_meta_connections)
+   - [phone_numbers](#5-phone_numbers)
+   - [users](#6-users)
+   - [user_clinic_assignments](#7-user_clinic_assignments)
+   - [refresh_tokens](#8-refresh_tokens)
+   - [plans](#9-plans)
+   - [agents](#10-agents)
+   - [calls](#11-calls)
+   - [call_details](#12-call_details)
+   - [leads](#13-leads)
+   - [outbound_campaigns](#14-outbound_campaigns)
+   - [outbound_campaign_entries](#15-outbound_campaign_entries)
+   - [whatsapp_chats](#16-whatsapp_chats)
+   - [whatsapp_sessions](#17-whatsapp_sessions)
+   - [whatsapp_messages](#18-whatsapp_messages)
+   - ~~whatsapp_contact_profiles~~ — **REMOVED**, replaced by [patients](#36-patients)
+   - [operator_requests](#20-operator_requests)
+   - [appointments](#21-appointments)
+   - [appointment_validation_batches](#22-appointment_validation_batches)
+   - [appointment_validation_entries](#23-appointment_validation_entries)
+   - [billing_events](#24-billing_events)
+   - [payments](#25-payments)
+   - [billing_period_snapshots](#26-billing_period_snapshots)
+   - [billing_alerts](#27-billing_alerts)
+   - [stt_usages](#28-stt_usages)
+   - [logs](#29-logs)
+   - [audit_logs](#30-audit_logs)
+   - [tool_execution_logs](#31-tool_execution_logs)
+   - [migrations](#32-migrations)
+   - [transcriptions](#33-transcriptions)
+   - [summaries](#34-summaries)
+   - [whatsapp_recipients](#35-whatsapp_recipients)
+   - [patients](#36-patients)
+   - [patient_medical_histories](#37-patient_medical_histories)
+   - [patient_documents](#38-patient_documents)
+   - [patient_notes](#39-patient_notes)
+   - [treatments](#40-treatments)
+   - [treatment_plans](#41-treatment_plans)
+   - [treatment_plan_items](#42-treatment_plan_items)
+   - [doctor_profiles](#43-doctor_profiles)
+   - [patient_photo_sets](#44-patient_photo_sets)
+   - [patient_photos](#45-patient_photos)
+   - [examination_records](#46-examination_records)
+
+---
+
+## Naming Convention
+
+All column names follow the pattern `{table_prefix}_{field_name}`. This avoids ambiguity in joins and makes it immediately clear which table a column belongs to.
+
+| Table | Prefix | Example PK | Example FK |
+|-------|--------|-----------|-----------|
+| tenants | `tenant_` | `tenant_id` | -- |
+| clinics | `clinic_` | `clinic_id` | `clinic_tenant_id` |
+| clinic_calendar_connections | `calcn_` | `calcn_id` | `calcn_clinic_id` |
+| clinic_meta_connections | `meta_` | `meta_id` | `meta_clinic_id` |
+| phone_numbers | `phone_` | `phone_id` | `phone_tenant_id` |
+| users | `user_` | `user_id` | `user_tenant_id` |
+| user_clinic_assignments | `assign_` | `assign_id` | `assign_user_id` |
+| refresh_tokens | `token_` | `token_id` | `token_user_id` |
+| plans | `plan_` | `plan_id` | -- |
+| agents | `agent_` | `agent_id` | `agent_tenant_id` |
+| calls | `call_` | `call_id` | `call_tenant_id` |
+| call_details | `detail_` | `detail_id` | `detail_call_id` |
+| leads | `lead_` | `lead_id` | `lead_tenant_id` |
+| outbound_campaigns | `campaign_` | `campaign_id` | `campaign_tenant_id` |
+| outbound_campaign_entries | `centry_` | `centry_id` | `centry_campaign_id` |
+| whatsapp_chats | `chat_` | `chat_id` | `chat_tenant_id` |
+| whatsapp_sessions | `session_` | `session_id` | `session_tenant_id` |
+| whatsapp_messages | `msg_` | `msg_id` | `msg_tenant_id` |
+| whatsapp_contact_profiles | `contact_` | `contact_id` | `contact_tenant_id` |
+| operator_requests | `opreq_` | `opreq_id` | `opreq_tenant_id` |
+| appointments | `appt_` | `appt_id` | `appt_tenant_id` |
+| appointment_validation_batches | `batch_` | `batch_id` | `batch_tenant_id` |
+| appointment_validation_entries | `bentry_` | `bentry_id` | `bentry_batch_id` |
+| billing_events | `billing_` | `billing_id` | `billing_tenant_id` |
+| payments | `payment_` | `payment_id` | `payment_tenant_id` |
+| billing_period_snapshots | `snapshot_` | `snapshot_id` | `snapshot_tenant_id` |
+| billing_alerts | `alert_` | `alert_id` | `alert_tenant_id` |
+| stt_usages | `stt_` | `stt_id` | `stt_tenant_id` |
+| logs | `log_` | `log_id` | -- |
+| audit_logs | `audit_` | `audit_id` | -- |
+| tool_execution_logs | `toollog_` | `toollog_id` | -- |
+| migrations | `migration_` | `migration_id` | -- |
+| transcriptions | `tx_` | `tx_id` | -- |
+| summaries | `summary_` | `summary_id` | `summary_transcription_id` |
+| whatsapp_recipients | `recipient_` | `recipient_id` | -- |
+| patients | `patient_` | `patient_id` | `patient_tenant_id` |
+| patient_medical_histories | `history_` | `history_id` | `history_patient_id` |
+| patient_documents | `doc_` | `doc_id` | `doc_patient_id` |
+| patient_notes | `note_` | `note_id` | `note_patient_id` |
+| treatments | `treatment_` | `treatment_id` | `treatment_tenant_id` |
+| treatment_plans | `tplan_` | `tplan_id` | `tplan_patient_id` |
+| treatment_plan_items | `tpitem_` | `tpitem_id` | `tpitem_plan_id` |
+| doctor_profiles | `dprofile_` | `dprofile_id` | `dprofile_user_id` |
+| patient_photo_sets | `photoset_` | `photoset_id` | `photoset_patient_id` |
+| patient_photos | `photo_` | `photo_id` | `photo_set_id` |
+| examination_records | `exam_` | `exam_id` | `exam_appointment_id` |
+
+**General rules:**
+- Table names: `snake_case`, plural.
+- Primary keys: `{prefix}_id`, UUID, auto-generated with `@default(uuid())`.
+- Foreign keys: `{prefix}_{referenced_table}_id` (e.g., `user_tenant_id` references `tenants.tenant_id`).
+- Timestamps: `{prefix}_created_at`, `{prefix}_updated_at`.
+- All UUIDs are v4 strings.
+- All timestamps are `DateTime` stored as `timestamptz`.
+
+---
+
+## Enums
+
+All enums used across the schema. Listed alphabetically.
+
+### AlertService
+
+Alert threshold service types for billing alerts.
+
+| Value | Description |
+|-------|-------------|
+| `inbound_minutes` | Inbound call minutes usage |
+| `inbound_calls` | Inbound call count |
+| `wa_chats` | WhatsApp billable chat count |
+| `billing_period` | Billing period expiration |
+
+### AlertType
+
+Billing alert threshold levels.
+
+| Value | Description |
+|-------|-------------|
+| `usage_75` | 75% of plan limit reached |
+| `usage_90` | 90% of plan limit reached |
+| `usage_100` | 100% of plan limit reached (overage begins) |
+| `period_expiring` | Billing period about to expire |
+
+### AppointmentSource
+
+How the appointment was created.
+
+| Value | Description |
+|-------|-------------|
+| `whatsapp` | Booked via WhatsApp AI chat |
+| `voice_call` | Booked during a voice call |
+| `dashboard` | Manually booked by staff from the admin panel |
+| `walk_in` | Walk-in patient registered at reception |
+
+### AppointmentStatus
+
+Current state of an appointment.
+
+| Value | Description |
+|-------|-------------|
+| `scheduled` | Booked, upcoming |
+| `confirmed` | Patient confirmed attendance (via validation call or manual) |
+| `in_progress` | Patient is currently being seen |
+| `completed` | Visit finished |
+| `cancelled` | Cancelled before visit |
+| `no_show` | Patient did not show up |
+
+### AppointmentType
+
+What kind of visit this appointment represents.
+
+| Value | Description |
+|-------|-------------|
+| `appointment` | Standard scheduled appointment |
+| `walk_in` | Walk-in patient (registered on arrival) |
+| `follow_up` | Follow-up visit for a previous treatment |
+| `consultation` | Initial consultation / examination |
+
+### BatchStatus
+
+Lifecycle state of an appointment validation batch.
+
+| Value | Description |
+|-------|-------------|
+| `draft` | Created, not yet submitted |
+| `submitted` | Sent to ElevenLabs for processing |
+| `in_progress` | Calls are being made |
+| `completed` | All calls finished |
+| `cancelled` | Batch was cancelled before completion |
+
+### BillingEventType
+
+Type of billing event for charge tracking.
+
+| Value | Description |
+|-------|-------------|
+| `call_charge` | Per-minute charge for a voice call |
+| `subscription` | Recurring subscription charge |
+| `top_up` | Extra minutes purchased |
+| `refund` | Refund issued |
+
+### CallDirection
+
+Direction of a voice call.
+
+| Value | Description |
+|-------|-------------|
+| `inbound` | Patient called the clinic |
+| `outbound` | System called the patient (campaigns, validation) |
+
+### CallStatus
+
+Final outcome of a voice call.
+
+| Value | Description |
+|-------|-------------|
+| `completed` | Call connected and ended normally |
+| `failed` | Call could not be placed or errored |
+| `no_answer` | Patient did not pick up |
+| `voicemail` | Call went to voicemail |
+| `transferred` | Call was transferred to another number |
+
+### CampaignEntryStatus
+
+Status of a single entry in an outbound campaign.
+
+| Value | Description |
+|-------|-------------|
+| `pending` | Waiting to be called |
+| `calling` | Call in progress |
+| `completed` | Call finished successfully |
+| `failed` | Call failed after all retries |
+| `no_answer` | No answer after all retries |
+| `voicemail` | Reached voicemail |
+
+### ChatChannel
+
+Which messaging platform the chat originates from.
+
+| Value | Description |
+|-------|-------------|
+| `whatsapp` | WhatsApp message |
+| `instagram` | Instagram direct message |
+
+### EntryCallStatus
+
+Status of a single entry in an appointment validation batch. Identical values to CampaignEntryStatus but semantically separate.
+
+| Value | Description |
+|-------|-------------|
+| `pending` | Waiting to be called |
+| `calling` | Call in progress |
+| `completed` | Call finished |
+| `failed` | Call failed |
+| `no_answer` | No answer |
+| `voicemail` | Reached voicemail |
+
+### LeadStatus
+
+Lifecycle stage of a sales lead.
+
+| Value | Description |
+|-------|-------------|
+| `new_lead` | Just created (named `new_lead` because `new` is a reserved word) |
+| `contacted` | Staff has reached out |
+| `appointment_scheduled` | Appointment booked |
+| `completed` | Lead converted to patient |
+| `lost` | Lead did not convert |
+| `expired` | Auto-expired after 24 hours with no action |
+
+### MessageSender
+
+Who sent a WhatsApp message.
+
+| Value | Description |
+|-------|-------------|
+| `contact` | The patient/external person |
+| `ai` | The AI agent |
+| `human` | A human staff member via live chat |
+| `system` | System-generated message (e.g., operator request notification) |
+
+### MigrationStatus
+
+Result of a data migration run.
+
+| Value | Description |
+|-------|-------------|
+| `success` | Migration completed without errors |
+| `failed` | Migration encountered an error |
+
+### NotificationDeliveryStatus
+
+Status of a notification delivery (used for post-call summary notifications).
+
+| Value | Description |
+|-------|-------------|
+| `pending` | Not yet sent |
+| `sending` | In the process of being sent |
+| `sent` | Successfully delivered |
+| `failed` | Delivery failed |
+
+### OperatorRequestStatus
+
+State of an operator (doctor) request in the operator-in-the-loop workflow.
+
+| Value | Description |
+|-------|-------------|
+| `pending` | Forwarded to doctor, awaiting response |
+| `responded` | Doctor replied with price/instructions |
+| `expired` | Doctor did not respond within timeout |
+| `cancelled` | Request was cancelled |
+
+### OutboundCampaignStatus
+
+Lifecycle state of an outbound campaign.
+
+| Value | Description |
+|-------|-------------|
+| `draft` | Being configured, not yet started |
+| `scheduled` | Configured and waiting for scheduled start time |
+| `running` | Actively making calls |
+| `paused` | Temporarily paused (can be resumed) |
+| `completed` | All entries processed |
+
+### PaymentMethod
+
+How a tenant payment was made.
+
+| Value | Description |
+|-------|-------------|
+| `cash` | Cash payment |
+| `bank_transfer` | Wire/bank transfer |
+| `other` | Other payment method |
+
+### PaymentType
+
+Type of tenant payment.
+
+| Value | Description |
+|-------|-------------|
+| `subscription` | Monthly/periodic subscription |
+| `top_up` | Extra minutes or usage purchase |
+
+### PhoneNumberProvider
+
+Which system manages the phone number.
+
+| Value | Description |
+|-------|-------------|
+| `meta_business` | Official Meta Business Cloud API |
+| `elevenlabs` | ElevenLabs SIP trunk (voice calls) |
+
+### PhoneNumberPurpose
+
+What the phone number is used for.
+
+| Value | Description |
+|-------|-------------|
+| `whatsapp` | WhatsApp messaging |
+| `inbound_call` | Receiving voice calls |
+| `outbound_call` | Making voice calls (campaigns, validation) |
+
+### PostCallStrategy
+
+What happens after a voice call ends.
+
+| Value | Description |
+|-------|-------------|
+| `summarize` | AI generates a summary of the call |
+| `none` | No post-call processing |
+
+### Sentiment
+
+AI-detected sentiment of a conversation.
+
+| Value | Description |
+|-------|-------------|
+| `positive` | Positive tone/outcome |
+| `neutral` | Neutral tone |
+| `negative` | Negative tone/outcome |
+
+### SessionResolvedBy
+
+How a WhatsApp session was resolved (ended).
+
+| Value | Description |
+|-------|-------------|
+| `human` | Staff took over and resolved |
+| `ai_timeout` | AI finished conversation naturally |
+| `timeout` | Session expired due to inactivity (2-hour sweep) |
+| `manual` | Staff manually resolved without taking over |
+
+### SessionStatus
+
+Current state of a WhatsApp chat session.
+
+| Value | Description |
+|-------|-------------|
+| `waiting` | Grace period active, waiting to see if human responds first |
+| `active` | AI is handling the conversation |
+| `resolved` | Session is closed |
+
+### TranscriptionProcessingStatus
+
+Pipeline state for post-call transcription processing.
+
+| Value | Description |
+|-------|-------------|
+| `pending` | Transcription received, not yet summarized |
+| `summarizing` | AI summary generation in progress |
+| `summarized` | Summary complete |
+| `notified` | Summary notification sent to staff |
+| `failed` | Processing failed |
+
+### UserRole
+
+User roles in the system. Platform roles (superadmin, sales) have no tenant. Tenant roles are scoped to a tenant and further restricted by clinic assignments.
+
+| Value | Description |
+|-------|-------------|
+| `superadmin` | Platform operator -- all endpoints, all tenants, bypasses all checks |
+| `sales` | Platform sales team -- create tenants, assign plans, no access to tenant data |
+| `owner` | Clinic chain owner -- full access to all clinics within the tenant |
+| `admin` | Branch administrator -- full access to assigned clinics |
+| `doctor` | Doctor/specialist -- patient history, operator requests, appointments |
+| `receptionist` | Front desk staff -- live chat, appointments, calls, leads |
+
+### ValidationResult
+
+Outcome of an appointment validation call.
+
+| Value | Description |
+|-------|-------------|
+| `confirmed` | Patient confirmed the appointment |
+| `cancelled` | Patient wants to cancel |
+| `reschedule` | Patient wants to reschedule |
+| `unresolved` | Could not determine outcome (e.g., call too short, no tool fired) |
+
+### TreatmentPlanStatus
+
+Lifecycle state of a treatment plan.
+
+| Value | Description |
+|-------|-------------|
+| `active` | Plan is in progress, items being worked on |
+| `completed` | All items completed |
+| `cancelled` | Plan was cancelled |
+
+### TreatmentPlanItemStatus
+
+Status of a single item within a treatment plan.
+
+| Value | Description |
+|-------|-------------|
+| `planned` | Not yet scheduled |
+| `scheduled` | Appointment linked |
+| `in_progress` | Currently being performed |
+| `completed` | Done |
+| `cancelled` | Cancelled |
+
+---
+
+## Table Definitions
+
+---
+
+### 1. tenants
+
+**Purpose:** Root entity for multi-tenancy. Each tenant is a healthcare clinic or clinic chain. The tenant is a **thin shell** — it holds identity, billing, feature flags, and compliance. All operational configuration lives on the clinic level.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `tenant_id` | UUID | Yes | `uuid()` | Primary key |
+| `tenant_name` | String | Yes | -- | Display name (e.g., "Gueluestuek Dental") |
+| `tenant_plan_id` | UUID | No | `null` | FK to `plans`. Null means no active plan |
+| `tenant_enabled_features` | String[] | Yes | `[]` | Feature flags. See Feature Flags section in system overview |
+| `tenant_is_active` | Boolean | Yes | `true` | Soft-disable toggle. Inactive tenants cannot use the system |
+| `tenant_deleted_at` | DateTime | No | `null` | Soft-delete timestamp. Non-null means tenant is deleted |
+| `tenant_kvkk_consent` | Boolean | Yes | `false` | Whether tenant has accepted KVKK/GDPR data processing terms |
+| `tenant_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `tenant_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `tenant_id` | PK lookup |
+| `idx_tenants_plan` | `tenant_plan_id` | Find tenants by plan (billing, plan changes) |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | plans | `tenant_plan_id` | Current subscription plan |
+| has_many | users, clinics, agents, phone_numbers, patients, treatments, calls, leads, outbound_campaigns, whatsapp_chats, whatsapp_sessions, whatsapp_messages, operator_requests, appointments, appointment_validation_batches, billing_events, payments, billing_period_snapshots, billing_alerts, stt_usages | -- | All business data |
+
+**Design decisions:**
+- **Tenant is thin.** All operational configuration (language, AI provider, grace period, notification phones, operator settings) lives on the clinic. No inheritance chain — each clinic is self-contained with its own defaults.
+- Feature flags are stored as a simple `String[]` rather than a separate table. The list is small (13 flags), queried on every request (embedded in JWT), and rarely updated.
+- Billing (`plan_id`) is tenant-level because a clinic chain pays one subscription, not per-branch.
+- KVKK consent is tenant-level because it is a legal agreement by the business entity.
+- Soft delete via `tenant_deleted_at` rather than hard delete to preserve billing history and audit trail.
+
+**What moved to clinic:** Language, AI provider/model, SMS config, notification phones, grace period, operator prefix/timeout, appointment duration, profile agent. See [clinics](#2-clinics).
+
+---
+
+### 2. clinics
+
+**Purpose:** Represents a physical clinic branch/location within a tenant. A single-clinic tenant has exactly one clinic (auto-created, `clinic_is_default = true`). Multi-clinic tenants have one per branch. The clinic is the **primary configuration entity** — all operational settings live here. No inheritance from tenant.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `clinic_id` | UUID | Yes | `uuid()` | Primary key |
+| `clinic_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `clinic_name` | String | Yes | -- | Display name (e.g., "Kadikoy Branch") |
+| `clinic_slug` | String | Yes | -- | URL-friendly identifier (e.g., `"kadikoy"`, `"main"`) |
+| `clinic_address` | String | Yes | `""` | Physical address |
+| `clinic_phone` | String | Yes | `""` | Clinic contact phone (for display, not WhatsApp routing) |
+| `clinic_email` | String | Yes | `""` | Clinic contact email |
+| `clinic_timezone` | String | Yes | `"Europe/Istanbul"` | IANA timezone |
+| `clinic_is_default` | Boolean | Yes | `false` | True for the auto-created first clinic in single-clinic tenants |
+| `clinic_is_active` | Boolean | Yes | `true` | Soft-disable toggle |
+| `clinic_language` | String | Yes | `"tr"` | Default language for AI agents and UI at this clinic |
+| `clinic_ai_provider` | String | Yes | `"openai"` | AI provider: `"openai"` or `"anthropic"` |
+| `clinic_ai_model` | String | Yes | `""` | AI model override. Empty = use provider default |
+| `clinic_grace_period_seconds` | Int | Yes | `180` | Seconds before AI activates on a new message |
+| `clinic_operator_phone` | String | No | `null` | Doctor's WhatsApp number for operator workflow |
+| `clinic_operator_prefix` | String | Yes | `"R"` | REF code prefix for operator requests (e.g., `R-AB2X`) |
+| `clinic_operator_timeout_hours` | Int | Yes | `24` | Hours before an operator request expires |
+| `clinic_ai_shift_enabled` | Boolean | Yes | `false` | Whether AI only operates during specific hours |
+| `clinic_ai_shift_schedule` | Json | Yes | `"[]"` | Array of `{day, start, end}` objects defining AI operating hours |
+| `clinic_blacklisted_numbers` | String[] | Yes | `[]` | Phone numbers blocked from this clinic's AI agent |
+| `clinic_fixed_first_message` | String | No | `null` | Fixed first message sent to new contacts. Null = disabled |
+| `clinic_sms_enabled` | Boolean | Yes | `false` | Whether SMS notifications are enabled |
+| `clinic_sms_phones` | String[] | Yes | `[]` | Staff phone numbers for SMS notifications |
+| `clinic_notification_phones` | String[] | Yes | `[]` | General notification recipient phone numbers |
+| `clinic_message_retention_days` | Int | Yes | `7` | Days to keep WhatsApp/Instagram messages before auto-deletion |
+| `clinic_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `clinic_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `clinic_id` | PK lookup |
+| Unique | `(clinic_tenant_id, clinic_slug)` | Ensure slug uniqueness within a tenant |
+| `idx_clinics_tenant` | `clinic_tenant_id` | List all clinics for a tenant |
+| `idx_clinics_operator` | `(clinic_tenant_id, clinic_operator_phone)` | Look up clinic when doctor replies to operator request |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `clinic_tenant_id` | Parent tenant (cascade delete) |
+| has_many | user_clinic_assignments | -- | Users assigned to this clinic |
+| has_many | agents, phone_numbers | -- | Clinic-scoped agents and numbers |
+| has_one | clinic_calendar_connections | -- | Google Calendar connection |
+| has_many | clinic_meta_connections | -- | Meta Business API connections (WhatsApp + Instagram) |
+| has_many | patients, treatments, treatment_plans | -- | Clinic-scoped CRM data |
+| has_many | whatsapp_chats, whatsapp_sessions, appointments, operator_requests, calls, leads, outbound_campaigns, appointment_validation_batches | -- | Clinic-scoped operational data |
+
+**Design decisions:**
+- **Clinic owns all config.** No inheritance from tenant. Each clinic is self-contained. When a new clinic is created, it gets sensible defaults. This eliminates the "check clinic → fall back to tenant → fall back to system" resolution chain.
+- All config fields are **non-nullable with defaults**. No null-means-inherit pattern.
+- `clinic_phone` and `clinic_email` are for display purposes (e.g., shown on appointment confirmations). They are NOT the WhatsApp number — WhatsApp routing uses the `phone_numbers` table.
+- `clinic_settings` JSONB was removed. All config is now in proper columns. If edge-case config is needed later, it can be added back.
+- Operator workflow fields are top-level columns because they are queried on every incoming WhatsApp message.
+- `clinic_ai_provider` / `clinic_ai_model` control which AI provider is used for background processing (summaries, labels, extraction) at this clinic. Per-agent overrides still exist on the `agents` table.
+
+---
+
+### 3. clinic_calendar_connections
+
+**Purpose:** Stores Google Calendar OAuth2 connection details for a clinic. Extracted from JSONB to enable proper indexing and encrypted token storage. One-to-one with `clinics`.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `calcn_id` | UUID | Yes | `uuid()` | Primary key |
+| `calcn_clinic_id` | UUID | Yes (unique) | -- | FK to `clinics`. One-to-one relationship |
+| `calcn_google_email` | String | No | `null` | Google account email used for calendar |
+| `calcn_encrypted_refresh_token` | String | No | `null` | AES-256-GCM encrypted OAuth2 refresh token |
+| `calcn_calendar_id` | String | No | `null` | Google Calendar ID (e.g., `primary` or specific calendar) |
+| `calcn_calendar_name` | String | No | `null` | Display name of the selected calendar |
+| `calcn_appointment_duration` | Int | Yes | `30` | Default appointment duration in minutes. Overridden by treatment or doctor duration when specified |
+| `calcn_working_hours` | Json | Yes | `"[]"` | Array of `{day, start, end}` objects defining clinic-wide appointment hours |
+| `calcn_blocked_dates` | Json | Yes | `"[]"` | Array of `{date, reason}` objects for holidays/closures |
+| `calcn_connected_at` | DateTime | No | `null` | When the Google Calendar was connected |
+| `calcn_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `calcn_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `calcn_id` | PK lookup |
+| Unique | `calcn_clinic_id` | Enforce one-to-one with clinics |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | clinics | `calcn_clinic_id` | Parent clinic (cascade delete) |
+
+**Design decisions:**
+- One-to-one with clinics via unique constraint on `calcn_clinic_id`.
+- Timezone is not stored here — uses `clinic.clinic_timezone` for all Calendar API calls.
+- Refresh token is AES-256-GCM encrypted using `GOOGLE_TOKEN_ENCRYPTION_KEY`. Access tokens are cached in Redis (`gcal:token:{clinicId}`) with a 50-minute TTL.
+- `calcn_appointment_duration` is the clinic-wide default. Priority chain for slot duration: `treatment.duration_minutes` > `doctor.profile_appointment_duration` > `calcn_appointment_duration` (30 min).
+- Working hours define clinic-wide availability. Doctor-specific hours are on `doctor_profiles.profile_working_hours`. Both are checked during slot generation.
+- Working hours and blocked dates remain as JSONB because they are variable-length arrays loaded in bulk (never queried individually).
+
+---
+
+### 4. clinic_meta_connections
+
+**Purpose:** Stores Meta Business API connection details for a clinic. Each row is one connection — either a WhatsApp Business Account (WABA) or an Instagram page. A clinic can have multiple of each.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `meta_id` | UUID | Yes | `uuid()` | Primary key |
+| `meta_clinic_id` | UUID | Yes | -- | FK to `clinics`. Many-to-one (a clinic can have multiple connections) |
+| `meta_type` | String | Yes | -- | Connection type: `whatsapp` or `instagram` |
+| `meta_label` | String | Yes | `""` | Display label (e.g., "Main WhatsApp", "Dr. Ayse Instagram") |
+| `meta_waba_id` | String | No | `null` | WhatsApp Business Account ID. Set when `meta_type = 'whatsapp'` |
+| `meta_phone_number_id` | String | No | `null` | Meta-assigned phone number ID. Set when `meta_type = 'whatsapp'` |
+| `meta_display_phone` | String | No | `null` | Human-readable phone number. Set when `meta_type = 'whatsapp'` |
+| `meta_instagram_page_id` | String | No | `null` | Instagram Business Account page ID. Set when `meta_type = 'instagram'` |
+| `meta_encrypted_access_token` | String | No | `null` | AES-256-GCM encrypted access token (WABA token or page token depending on type) |
+| `meta_is_active` | Boolean | Yes | `true` | Whether this connection is active |
+| `meta_connected_at` | DateTime | No | `null` | When this connection was established |
+| `meta_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `meta_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `meta_id` | PK lookup |
+| `idx_meta_clinic` | `meta_clinic_id` | List all connections for a clinic |
+| `idx_meta_clinic_type` | `(meta_clinic_id, meta_type)` | List WhatsApp or Instagram connections for a clinic |
+| `idx_meta_phone_number` | `meta_phone_number_id` | Webhook routing: resolve incoming WhatsApp message to clinic |
+| `idx_meta_instagram_page` | `meta_instagram_page_id` | Webhook routing: resolve incoming Instagram DM to clinic |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | clinics | `meta_clinic_id` | Parent clinic (cascade delete) |
+
+**Design decisions:**
+- **1:many with clinic** (not 1:1). A clinic can have multiple WABAs (rare but possible — different brands) and multiple Instagram pages (common — main brand + individual doctor pages).
+- Meta Business API is the **sole WhatsApp provider** in the system. No Baileys/self-hosted bridge.
+- `meta_type` determines which fields are populated. WhatsApp connections use `waba_id`, `phone_number_id`, `display_phone`. Instagram connections use `instagram_page_id`. Both use `encrypted_access_token`.
+- Single `encrypted_access_token` field works for both types. For WhatsApp it's the WABA access token. For Instagram it's the page access token. Both encrypted with `META_TOKEN_ENCRYPTION_KEY`.
+- Old design had separate `encrypted_page_token` for Instagram — merged into `encrypted_access_token` since each row is now one connection type.
+- `meta_phone_number_id` and `meta_instagram_page_id` are indexed for webhook routing. When a Meta webhook arrives, the system looks up the connection by phone_number_id or page_id to resolve the clinic.
+
+---
+
+### 5. phone_numbers
+
+**Purpose:** Central registry for all phone numbers across all uses. Each number has one purpose (WhatsApp, inbound call, or outbound call) and links to a clinic and agent for routing. This is how the system knows which clinic and AI agent handle an incoming message or call.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `phone_id` | UUID | Yes | `uuid()` | Primary key |
+| `phone_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `phone_clinic_id` | UUID | No | `null` | FK to `clinics`. Null = shared across clinics (e.g., outbound line for the whole chain) |
+| `phone_number` | String | Yes | -- | Phone number in E.164 format (e.g., `+905551234567`) |
+| `phone_label` | String | Yes | `""` | Human-readable label (e.g., "Main WhatsApp", "Reception Line") |
+| `phone_purpose` | PhoneNumberPurpose | Yes | -- | `whatsapp`, `inbound_call`, or `outbound_call` |
+| `phone_provider` | PhoneNumberProvider | Yes | -- | `meta_business` or `elevenlabs` |
+| `phone_external_account_id` | String | No | `null` | Meta phone_number_id (for WhatsApp numbers) |
+| `phone_elevenlabs_phone_id` | String | No | `null` | ElevenLabs phone number ID (for voice call numbers) |
+| `phone_elevenlabs_agent_id` | String | No | `null` | ElevenLabs agent ID (external, on the ElevenLabs side) |
+| `phone_agent_id` | UUID | No | `null` | FK to `agents`. Internal agent routing |
+| `phone_wa_connected` | Boolean | Yes | `false` | Whether WhatsApp is currently connected on this number |
+| `phone_wa_connected_at` | DateTime | No | `null` | When WhatsApp was last connected |
+| `phone_wa_bridge_provider` | String | No | `null` | WhatsApp bridge: `meta_business` or `baileys` (Baileys reserved for future) |
+| `phone_schedule_enabled` | Boolean | Yes | `false` | Whether time-based scheduling is active (inbound call numbers) |
+| `phone_schedule` | Json | Yes | `"[]"` | Array of `{day, start, end}` schedule windows for agent assignment |
+| `phone_agent_assigned` | Boolean | Yes | `false` | Whether the ElevenLabs agent is currently assigned to this number |
+| `phone_is_active` | Boolean | Yes | `true` | Soft-disable toggle |
+| `phone_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `phone_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `phone_id` | PK lookup |
+| Unique | `(phone_tenant_id, phone_number, phone_purpose)` | Prevent duplicate registration of the same number for the same purpose |
+| `idx_phones_tenant_purpose` | `(phone_tenant_id, phone_purpose)` | List numbers by purpose |
+| `idx_phones_clinic` | `phone_clinic_id` | List numbers assigned to a clinic |
+| `idx_phones_provider_external` | `(phone_provider, phone_external_account_id)` | Resolve Meta webhook to our phone number record |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `phone_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `phone_clinic_id` | Assigned clinic (optional) |
+| belongs_to | agents | `phone_agent_id` | Internal agent routing |
+| has_many | whatsapp_chats | -- | Chats received on this number |
+| has_many | outbound_campaigns | -- | Campaigns using this number for outbound calls |
+| has_many | appointment_validation_batches | -- | Validation batches using this number |
+
+**Design decisions:**
+- The unique constraint `(tenant_id, number, purpose)` allows the same physical number to serve multiple purposes (e.g., a number can be both `whatsapp` and `inbound_call`).
+- `phone_elevenlabs_agent_id` is the external ElevenLabs agent ID, while `phone_agent_id` is the FK to our internal `agents` table. Both are needed because the internal agent stores our config while the ElevenLabs ID is used for API calls.
+- `phone_wa_connected`, `phone_wa_connected_at`, `phone_wa_bridge_provider` are kept for future Baileys integration. At launch, only `meta_business` is used as bridge provider. Fields default to false/null.
+- Schedule fields (`phone_schedule_enabled`, `phone_schedule`) are for inbound call numbers only — controls when the ElevenLabs agent is assigned/unassigned via the 15-minute schedule sync job.
+- `phone_clinic_id` is nullable because outbound call numbers may be shared across clinics in a multi-branch chain.
+
+---
+
+### 6. users
+
+**Purpose:** User accounts for the platform. Platform-level users (superadmin, sales) have `user_tenant_id = null`. Tenant-level users (owner, admin, doctor, receptionist) are scoped to a tenant and further restricted by clinic assignments.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `user_id` | UUID | Yes | `uuid()` | Primary key |
+| `user_tenant_id` | UUID | No | `null` | FK to `tenants`. Null for platform roles (superadmin, sales) |
+| `user_email` | String | Yes (unique) | -- | Login email. Globally unique across all tenants |
+| `user_password_hash` | String | Yes | -- | bcrypt hash (12 rounds) |
+| `user_role` | UserRole | Yes | `receptionist` | One of: `superadmin`, `sales`, `owner`, `admin`, `doctor`, `receptionist` |
+| `user_first_name` | String | Yes | -- | First name |
+| `user_last_name` | String | Yes | -- | Last name |
+| `user_phone` | String | No | `null` | Staff phone number (E.164). Used for SMS notifications, contact info |
+| `user_is_active` | Boolean | Yes | `true` | Soft-disable toggle. Inactive users cannot log in |
+| `user_last_login_at` | DateTime | No | `null` | Last successful login timestamp |
+| `user_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `user_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `user_id` | PK lookup |
+| Unique | `user_email` | Login lookup, prevent duplicate accounts |
+| `idx_users_tenant` | `user_tenant_id` | List all users for a tenant |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `user_tenant_id` | Parent tenant (cascade delete). Null for platform roles |
+| has_one | doctor_profiles | -- | Doctor-specific profile (specialty, working hours). Only for doctor role |
+| has_many | user_clinic_assignments | -- | Which clinics this user can access |
+| has_many | refresh_tokens | -- | Active refresh tokens |
+| has_many | whatsapp_messages | -- | Messages sent as human agent (`sender = 'human'`) |
+| has_many | whatsapp_sessions (TakenOverBy) | -- | Sessions this user took over |
+| has_many | payments (RecordedBy) | -- | Payments recorded by this user |
+| has_many | appointment_validation_batches (CreatedBy) | -- | Validation batches created by this user |
+| has_many | treatment_plans (PlanDoctor) | -- | Treatment plans managed by this doctor |
+| has_many | patient_notes (Author) | -- | Patient notes written by this user |
+| has_many | patient_documents (UploadedBy) | -- | Documents uploaded by this user |
+| has_many | patient_photo_sets (TakenBy) | -- | Photo sets taken by this user |
+
+**Design decisions:**
+- Email is globally unique (not per-tenant). A person can only have one account.
+- `user_tenant_id` is nullable so platform roles (superadmin, sales) can exist without a tenant.
+- `user_first_name` + `user_last_name` for consistency with the `patients` table. Display name computed as `"{first_name} {last_name}"`.
+- `user_phone` is optional. Used for SMS notifications to staff and as contact info in audit trail.
+- Password stored as bcrypt hash with 12 rounds. No plaintext, no reversible encryption.
+- 2FA (TOTP) can be added later as additional columns (`twoFactorSecret`, `twoFactorEnabled`, `twoFactorBackupCodes`). Not included at launch.
+
+---
+
+### 7. user_clinic_assignments
+
+**Purpose:** Junction table linking users to the clinics they can access. `owner` role users bypass this (they see all clinics). `admin`, `doctor`, and `receptionist` users only see data from their assigned clinics.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `assign_id` | UUID | Yes | `uuid()` | Primary key |
+| `assign_user_id` | UUID | Yes | -- | FK to `users` |
+| `assign_clinic_id` | UUID | Yes | -- | FK to `clinics` |
+| `assign_created_at` | DateTime | Yes | `now()` | When the assignment was created |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `assign_id` | PK lookup |
+| Unique | `(assign_user_id, assign_clinic_id)` | Prevent duplicate assignments |
+| `idx_assign_user` | `assign_user_id` | Get all clinics for a user (used by ClinicAccessGuard on every request) |
+| `idx_assign_clinic` | `assign_clinic_id` | Get all users for a clinic (user management page) |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | users | `assign_user_id` | The user (cascade delete) |
+| belongs_to | clinics | `assign_clinic_id` | The clinic (cascade delete) |
+
+**Design decisions:**
+- Simple junction table rather than embedding clinic IDs in the user record. This allows proper foreign key enforcement and easy querying from both directions.
+- Cascade delete on both sides: if a user is deleted, their assignments are removed. If a clinic is deleted, all assignments to it are removed.
+
+---
+
+### 8. refresh_tokens
+
+**Purpose:** Stores active refresh tokens for JWT authentication. Each login creates a new refresh token. Tokens are rotated on refresh (old token deleted, new one created).
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `token_id` | UUID | Yes | `uuid()` | Primary key |
+| `token_user_id` | UUID | Yes | -- | FK to `users` |
+| `token_value` | String | Yes (unique) | -- | The refresh token string (opaque) |
+| `token_expires_at` | DateTime | Yes | -- | When this token expires (30 days from creation) |
+| `token_created_at` | DateTime | Yes | `now()` | When this token was created |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `token_id` | PK lookup |
+| Unique | `token_value` | Token validation lookup |
+| `idx_tokens_user` | `token_user_id` | Revoke all tokens for a user (logout from all devices) |
+| `idx_tokens_expires` | `token_expires_at` | Cleanup expired tokens (BullMQ job) |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | users | `token_user_id` | Token owner (cascade delete) |
+
+**Design decisions:**
+- Refresh tokens live in PostgreSQL for persistence, plus a Redis set for fast revocation checks.
+- Token rotation: on each refresh, the old token is deleted and a new one is created. This limits the window of a stolen token.
+- Access tokens (15-minute TTL) are stateless JWTs -- not stored in the database. Revoked access tokens are tracked in a Redis blacklist that expires with the token's TTL.
+
+---
+
+### 9. plans
+
+**Purpose:** Subscription plan definitions. Each plan specifies usage limits (call minutes, chat count) and pricing. Tenants are assigned one plan at a time.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `plan_id` | UUID | Yes | `uuid()` | Primary key |
+| `plan_name` | String | Yes | -- | Display name (e.g., "Starter", "Professional") |
+| `plan_slug` | String | Yes (unique) | -- | URL-friendly identifier (e.g., `"starter"`, `"pro"`) |
+| `plan_price` | Decimal | Yes | -- | Monthly price in TRY |
+| `plan_overage_rate` | Decimal | Yes | -- | Per-minute charge when usage exceeds plan limits (TRY) |
+| `plan_included_inbound_minutes` | Int | Yes | `0` | Included inbound call minutes per billing period |
+| `plan_included_inbound_calls` | Int | Yes | `0` | Included inbound call count per billing period |
+| `plan_included_outbound_minutes` | Int | Yes | `0` | Included outbound call minutes per billing period |
+| `plan_included_outbound_calls` | Int | Yes | `0` | Included outbound call count per billing period |
+| `plan_included_wa_chats` | Int | Yes | `0` | Included WhatsApp billable chats per billing period |
+| `plan_is_active` | Boolean | Yes | `true` | Whether this plan can be assigned to new tenants |
+| `plan_sort_order` | Int | Yes | `0` | Display ordering in plan selection UI |
+| `plan_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `plan_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `plan_id` | PK lookup |
+| Unique | `plan_slug` | Lookup by slug (API, UI) |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| has_many | tenants | -- | Tenants on this plan |
+| has_many | billing_period_snapshots | -- | Historical snapshots referencing this plan |
+
+**Design decisions:**
+- Plans are global (not per-tenant). Created and managed by superadmin.
+- `Decimal` type for `plan_price` and `plan_overage_rate` to avoid floating-point rounding issues with currency.
+- `plan_sort_order` allows the admin to control the order plans appear in the UI without relying on alphabetical or creation-date sorting.
+
+---
+
+### 10. agents
+
+> **TODO:** Revisit this model later. Column structure depends on final ElevenLabs agent configuration decisions.
+
+**Purpose:** A configured ElevenLabs AI agent linked to a tenant or clinic. Agents are not tied to a specific phone number or call direction. The same agent can serve WhatsApp chat, inbound calls, and outbound campaigns via different `phone_numbers` records.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `agent_id` | UUID | Yes | `uuid()` | Primary key |
+| `agent_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `agent_clinic_id` | UUID | No | `null` | FK to `clinics`. Null means tenant-level (shared across clinics) |
+| `agent_elevenlabs_id` | String | Yes | -- | ElevenLabs agent ID (external identifier) |
+| `agent_name` | String | Yes | `""` | Display name in the dashboard |
+| `agent_description` | String | Yes | `""` | Description/notes |
+| `agent_voice_id` | String | Yes | `""` | ElevenLabs voice ID for this agent |
+| `agent_language` | String | Yes | `"tr"` | Agent language code |
+| `agent_greeting` | String | Yes | `""` | First message for voice calls |
+| `agent_system_prompt` | String | Yes | `""` | Custom system prompt override |
+| `agent_ai_provider` | String | No | `null` | AI provider override. Null inherits from tenant default |
+| `agent_ai_model` | String | No | `null` | AI model override. Null inherits from tenant/provider default |
+| `agent_post_call_strategy` | PostCallStrategy | Yes | `summarize` | What to do after a call ends |
+| `agent_post_call_wa_notify` | Boolean | Yes | `true` | Send WhatsApp notification with summary after call |
+| `agent_post_call_sms_notify` | Boolean | Yes | `false` | Send SMS notification with summary after call |
+| `agent_summary_prompt` | String | Yes | `""` | Custom prompt for AI summary generation |
+| `agent_wa_message_template` | String | Yes | `""` | Custom WhatsApp notification template |
+| `agent_extra_config` | Json | Yes | `"{}"` | Thin JSONB for truly dynamic edge-case config |
+| `agent_is_active` | Boolean | Yes | `true` | Soft-disable toggle |
+| `agent_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `agent_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `agent_id` | PK lookup |
+| `idx_agents_tenant` | `agent_tenant_id` | List all agents for a tenant |
+| `idx_agents_clinic` | `agent_clinic_id` | List agents for a clinic |
+| `idx_agents_elevenlabs` | `agent_elevenlabs_id` | Resolve ElevenLabs callbacks to our agent record |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `agent_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `agent_clinic_id` | Assigned clinic (optional) |
+| has_many | phone_numbers | -- | Phone numbers routing to this agent |
+| has_many | calls | -- | Calls handled by this agent |
+| has_many | outbound_campaigns | -- | Campaigns using this agent |
+| has_many | appointment_validation_batches | -- | Validation batches using this agent |
+
+**Design decisions:**
+- Voice and language config are top-level columns (not JSONB) because they are read on every call/session initiation.
+- `agent_ai_provider` and `agent_ai_model` are nullable -- the resolution chain is: agent override > clinic default (`clinic_ai_provider`/`clinic_ai_model`) > system env var (`DEFAULT_AI_PROVIDER`).
+- `agent_extra_config` JSONB is intentionally thin. If a field starts being queried frequently, it should be promoted to a column.
+
+---
+
+### 11. calls
+
+**Purpose:** Records every voice call (inbound and outbound). Contains metadata and summary-level data. Heavy content (transcript, recording, analysis) is in a separate `call_details` table for performance.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `call_id` | UUID | Yes | `uuid()` | Primary key |
+| `call_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `call_clinic_id` | UUID | Yes | -- | FK to `clinics`. Resolved from phone number (inbound) or campaign/agent (outbound) |
+| `call_patient_id` | UUID | No | `null` | FK to `patients`. Resolved by phone number match during post-call processing |
+| `call_agent_id` | UUID | Yes | -- | FK to `agents`. Which agent handled the call |
+| `call_campaign_id` | UUID | No | `null` | FK to `outbound_campaigns`. Non-null for campaign calls |
+| `call_conversation_id` | String | No | `null` | ElevenLabs conversation ID |
+| `call_direction` | CallDirection | Yes | -- | `inbound` or `outbound` |
+| `call_caller_number` | String | Yes | -- | Who initiated the call (E.164) |
+| `call_callee_number` | String | Yes | -- | Who was called (E.164) |
+| `call_duration_seconds` | Int | Yes | `0` | Call duration in seconds |
+| `call_start_time` | DateTime | No | `null` | When the call started |
+| `call_end_time` | DateTime | No | `null` | When the call ended |
+| `call_termination_reason` | String | No | `null` | Why the call ended (e.g., "user_hangup", "no_answer") |
+| `call_cost` | Decimal | No | `null` | Calculated cost in TRY |
+| `call_language` | String | No | `null` | Detected or configured language |
+| `call_elevenlabs_status` | String | No | `null` | ElevenLabs-reported status |
+| `call_status` | CallStatus | Yes | -- | Final call outcome |
+| `call_sentiment` | Sentiment | No | `null` | AI-detected sentiment |
+| `call_categories` | String[] | Yes | `[]` | AI-generated categories/tags |
+| `call_wa_notification_sent` | Boolean | Yes | `false` | Whether post-call WhatsApp notification was sent |
+| `call_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `call_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `call_id` | PK lookup |
+| `idx_calls_tenant_date` | `(call_tenant_id, call_created_at DESC)` | Paginated call list for a tenant (most recent first) |
+| `idx_calls_clinic_date` | `(call_clinic_id, call_created_at DESC)` | Paginated call list for a clinic |
+| `idx_calls_campaign_status` | `(call_campaign_id, call_status)` | Campaign results aggregation |
+| `idx_calls_tenant_direction_date` | `(call_tenant_id, call_direction, call_created_at DESC)` | Filter by direction (inbound/outbound) |
+| `idx_calls_conversation` | `call_conversation_id` | Resolve ElevenLabs webhook callbacks |
+| `idx_calls_tenant_callee` | `(call_tenant_id, call_callee_number)` | Find calls to a specific phone number |
+| `idx_calls_patient_date` | `(call_patient_id, call_created_at DESC)` | Patient call history (timeline) |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `call_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `call_clinic_id` | Assigned clinic |
+| belongs_to | patients | `call_patient_id` | Patient (resolved by phone match post-call) |
+| belongs_to | agents | `call_agent_id` | Agent that handled the call |
+| belongs_to | outbound_campaigns | `call_campaign_id` | Parent campaign (if outbound campaign call) |
+| has_one | call_details | -- | Detailed content (transcript, recording, analysis) |
+| has_many | billing_events | -- | Billing charges for this call |
+| has_many | leads | -- | Leads generated from this call |
+| has_many | outbound_campaign_entries | -- | Campaign entries linked to this call |
+
+**Design decisions:**
+- Heavy content (transcript, recording URL, analysis JSON) is in a separate `call_details` table. This keeps the `calls` table lean for list queries where you only need metadata.
+- `call_clinic_id` is required. Every call belongs to a clinic — resolved from the phone number (inbound) or campaign/agent config (outbound).
+- `call_patient_id` is nullable. Resolved by matching caller/callee phone against `patients.patient_phone` during post-call processing. Null if no matching patient exists (e.g., unknown caller).
+- `Decimal` for `call_cost` to avoid floating-point rounding.
+- Eight indexes -- calls are the most-queried table in the system (dashboard, analytics, billing, patient timeline).
+
+---
+
+### 12. call_details
+
+**Purpose:** Stores heavy content for a call (transcript, summary, recording, analysis). Loaded only when viewing a single call detail page. Separated from `calls` to keep list queries fast.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `detail_id` | UUID | Yes | `uuid()` | Primary key |
+| `detail_call_id` | UUID | Yes (unique) | -- | FK to `calls`. One-to-one relationship |
+| `detail_transcript` | String | Yes | `""` | Full call transcript |
+| `detail_llm_summary` | String | No | `null` | AI-generated summary of the call |
+| `detail_extracted_data` | Json | No | `null` | AI-extracted structured data (varies by agent/campaign) |
+| `detail_recording_url` | String | No | `null` | External recording URL (ElevenLabs) |
+| `detail_recording_key` | String | No | `null` | MinIO object key if recording is mirrored locally |
+| `detail_analysis` | Json | No | `null` | ElevenLabs analysis payload |
+| `detail_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `detail_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `detail_id` | PK lookup |
+| Unique | `detail_call_id` | Enforce one-to-one with calls, fast join |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | calls | `detail_call_id` | Parent call (cascade delete) |
+
+**Design decisions:**
+- Transcript and summary are `String` (TEXT in PostgreSQL) -- no length limit. Call transcripts can be very long.
+- `detail_extracted_data` is JSONB because the structure varies per agent/campaign extraction schema.
+- `detail_recording_key` is for optional local mirroring of recordings to MinIO. If null, `detail_recording_url` points to the external provider.
+
+---
+
+### 13. leads
+
+**Purpose:** Sales leads generated from calls and WhatsApp conversations. A lead represents a potential patient who expressed interest in a service.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `lead_id` | UUID | Yes | `uuid()` | Primary key |
+| `lead_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `lead_clinic_id` | UUID | Yes | -- | FK to `clinics`. Resolved from source call or chat |
+| `lead_patient_id` | UUID | No | `null` | FK to `patients`. Linked when patient exists |
+| `lead_call_id` | UUID | No | `null` | FK to `calls`. Source: voice call |
+| `lead_session_id` | UUID | No | `null` | FK to `whatsapp_sessions`. Source: WhatsApp session |
+| `lead_chat_id` | UUID | No | `null` | FK to `whatsapp_chats`. Source: WhatsApp chat |
+| `lead_name` | String | No | `null` | Patient/lead name |
+| `lead_phone` | String | Yes | -- | Phone number (E.164) |
+| `lead_service_of_interest` | String | No | `null` | What service the lead is interested in |
+| `lead_status` | LeadStatus | Yes | `new_lead` | Current lifecycle stage |
+| `lead_categories` | String[] | Yes | `[]` | AI-generated categories |
+| `lead_summary` | String | No | `null` | AI-generated summary of the lead interaction |
+| `lead_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `lead_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `lead_id` | PK lookup |
+| `idx_leads_tenant_date` | `(lead_tenant_id, lead_created_at DESC)` | Paginated lead list |
+| `idx_leads_tenant_status` | `(lead_tenant_id, lead_status)` | Filter by status |
+| `idx_leads_call` | `lead_call_id` | Find lead by source call |
+| `idx_leads_session` | `lead_session_id` | Find lead by source session |
+| `idx_leads_patient` | `lead_patient_id` | Find leads for a patient (timeline) |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `lead_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `lead_clinic_id` | Assigned clinic |
+| belongs_to | patients | `lead_patient_id` | Patient (linked when exists) |
+| belongs_to | calls | `lead_call_id` | Source call (nullable) |
+| belongs_to | whatsapp_sessions | `lead_session_id` | Source session (nullable) |
+| belongs_to | whatsapp_chats | `lead_chat_id` | Source chat (nullable) |
+
+**Design decisions:**
+- Lead source is captured via nullable FKs (`lead_call_id`, `lead_session_id`) rather than a polymorphic `source_type`/`source_id` pattern. This enables proper foreign key constraints and direct joins.
+- A lead can have both `lead_call_id` and `lead_session_id` null (e.g., manually created), or one of them set.
+- `lead_categories` uses a `String[]` array rather than a junction table. Categories are AI-generated tags, not a controlled vocabulary.
+
+---
+
+### 14. outbound_campaigns
+
+**Purpose:** Customizable outbound call campaigns. Each campaign defines its own agent configuration, extraction schema, and call schedule. Not tied to surveys -- fully flexible for any outbound calling use case (surveys, follow-ups, marketing, feedback collection).
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `campaign_id` | UUID | Yes | `uuid()` | Primary key |
+| `campaign_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `campaign_clinic_id` | UUID | Yes | -- | FK to `clinics`. Which branch runs this campaign |
+| `campaign_agent_id` | UUID | Yes | -- | FK to `agents`. Agent used for calls |
+| `campaign_name` | String | Yes | -- | Campaign name |
+| `campaign_description` | String | Yes | `""` | Campaign description |
+| `campaign_status` | OutboundCampaignStatus | Yes | `draft` | Current lifecycle state |
+| `campaign_agent_config` | Json | Yes | `"{}"` | Agent config: `{prompt, first_message, language, voice_id, extraction_schema, post_call_prompt}` |
+| `campaign_schedule` | Json | Yes | -- | Schedule: `{start_date, end_date, daily_start_time, daily_end_time, days_of_week, max_concurrent, max_retries, retry_delay_minutes}` |
+| `campaign_phone_id` | UUID | No | `null` | FK to `phone_numbers`. Outbound phone number |
+| `campaign_stats` | Json | Yes | `"{}"` | Aggregated stats: `{total, pending, calling, completed, failed, no_answer, voicemail}` |
+| `campaign_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `campaign_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `campaign_id` | PK lookup |
+| `idx_campaigns_tenant_status` | `(campaign_tenant_id, campaign_status)` | List campaigns filtered by status |
+| `idx_campaigns_clinic` | `campaign_clinic_id` | List campaigns for a clinic |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `campaign_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `campaign_clinic_id` | Scoped clinic |
+| belongs_to | agents | `campaign_agent_id` | Agent handling calls |
+| belongs_to | phone_numbers | `campaign_phone_id` | Outbound phone number |
+| has_many | outbound_campaign_entries | -- | Phone list entries |
+| has_many | calls | -- | Calls made for this campaign |
+
+**Design decisions:**
+- `campaign_agent_config` is JSONB because it contains a complex, campaign-specific configuration structure (prompt, extraction schema, etc.) that varies per campaign.
+- `campaign_stats` is a denormalized aggregate stored as JSONB. Updated after each call completes. Avoids expensive COUNT queries on the entries table for dashboard rendering.
+- State machine: `draft` -> `scheduled` -> `running` <-> `paused` -> `completed`. Only `draft` campaigns can be edited or deleted.
+
+---
+
+### 15. outbound_campaign_entries
+
+**Purpose:** Individual phone list entries within an outbound campaign. Each entry is one person to call, with their custom data and call results.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `centry_id` | UUID | Yes | `uuid()` | Primary key |
+| `centry_campaign_id` | UUID | Yes | -- | FK to `outbound_campaigns` |
+| `centry_phone` | String | Yes | -- | Phone number to call (E.164) |
+| `centry_contact_name` | String | Yes | `""` | Contact name |
+| `centry_custom_data` | Json | Yes | `"{}"` | Per-entry dynamic variables passed to agent (e.g., patient name, product) |
+| `centry_status` | CampaignEntryStatus | Yes | `pending` | Current call status |
+| `centry_attempts` | Int | Yes | `0` | Number of call attempts made |
+| `centry_max_attempts` | Int | Yes | `3` | Maximum retry attempts |
+| `centry_last_attempt_at` | DateTime | No | `null` | Timestamp of last call attempt |
+| `centry_conversation_id` | String | No | `null` | ElevenLabs conversation ID for the call |
+| `centry_call_id` | UUID | No | `null` | FK to `calls`. Linked after call completes |
+| `centry_call_duration_secs` | Int | Yes | `0` | Duration of the call |
+| `centry_extracted_data` | Json | No | `null` | AI-extracted data per campaign extraction_schema |
+| `centry_summary` | String | No | `null` | AI-generated call summary |
+| `centry_called_at` | DateTime | No | `null` | When the first call was made |
+| `centry_completed_at` | DateTime | No | `null` | When the entry reached terminal status |
+| `centry_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `centry_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `centry_id` | PK lookup |
+| `idx_centries_campaign_status` | `(centry_campaign_id, centry_status)` | Dispatch next entries, count by status |
+| `idx_centries_conversation` | `centry_conversation_id` | Resolve ElevenLabs post-call webhook to entry |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | outbound_campaigns | `centry_campaign_id` | Parent campaign (cascade delete) |
+| belongs_to | calls | `centry_call_id` | Linked call record |
+
+**Design decisions:**
+- `centry_custom_data` is JSONB because it is tenant-defined, varying per campaign. Passed to the AI agent as dynamic variables.
+- `centry_extracted_data` is JSONB because its structure is defined by the campaign's `extraction_schema`.
+- Cascade delete from campaign: deleting a campaign deletes all its entries.
+
+---
+
+### 16. whatsapp_chats
+
+**Purpose:** Represents a WhatsApp (or Instagram) conversation thread with a patient. Each unique patient-phone-number combination gets one chat record. A chat can have multiple sessions over time.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `chat_id` | UUID | Yes | `uuid()` | Primary key |
+| `chat_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `chat_clinic_id` | UUID | Yes | -- | FK to `clinics`. Resolved from receiving phone number |
+| `chat_patient_id` | UUID | No | `null` | FK to `patients`. Linked on first message (auto-created or matched by phone) |
+| `chat_channel` | ChatChannel | Yes | `whatsapp` | `whatsapp` or `instagram` |
+| `chat_external_id` | String | Yes | -- | Provider chat identifier (Meta conversation ID). Treated as opaque string |
+| `chat_phone_id` | UUID | No | `null` | FK to `phone_numbers`. Which of our numbers received this chat |
+| `chat_contact_name` | String | Yes | `"Bilinmiyor"` | Contact display name from WhatsApp/Instagram profile |
+| `chat_contact_phone` | String | Yes | `""` | Contact phone number (denormalized from patient) |
+| `chat_is_closed` | Boolean | Yes | `false` | Whether the chat is manually closed/archived |
+| `chat_active_session_id` | UUID | No | `null` | Currently active session (denormalized for fast lookup) |
+| `chat_last_message_at` | DateTime | Yes | `now()` | Timestamp of most recent message (for sorting) |
+| `chat_last_message_preview` | String | Yes | `""` | Preview text of the last message (for chat list UI) |
+| `chat_message_count` | Int | Yes | `0` | Total message count (denormalized) |
+| `chat_deleted_at` | DateTime | No | `null` | Soft-delete timestamp |
+| `chat_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `chat_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `chat_id` | PK lookup |
+| Unique | `(chat_tenant_id, chat_external_id)` | Prevent duplicate chats for the same external conversation |
+| `idx_chats_tenant_clinic` | `(chat_tenant_id, chat_clinic_id)` | List chats for a clinic |
+| `idx_chats_tenant_lastmsg` | `(chat_tenant_id, chat_last_message_at DESC)` | Chat list sorted by most recent message |
+| `idx_chats_tenant_phone` | `(chat_tenant_id, chat_contact_phone)` | Find chat by patient phone number |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `chat_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `chat_clinic_id` | Assigned clinic |
+| belongs_to | patients | `chat_patient_id` | Patient (linked on first message) |
+| belongs_to | phone_numbers | `chat_phone_id` | Receiving phone number |
+| has_many | whatsapp_sessions | -- | Sessions within this chat |
+| has_many | whatsapp_messages | -- | All messages |
+| has_many | operator_requests | -- | Operator requests from this chat |
+| has_many | appointments | -- | Appointments booked in this chat |
+| has_many | leads | -- | Leads generated from this chat |
+
+**Design decisions:**
+- `chat_contact_id` replaced by `chat_patient_id`. Links to `patients` table instead of the removed `whatsapp_contact_profiles`.
+- `chat_external_account_id` dropped — was a legacy field for backward compatibility. Clean rewrite doesn't need it.
+- `chat_clinic_id` is required. Resolved from the receiving phone number on first message.
+- Denormalized fields (`chat_last_message_at`, `chat_last_message_preview`, `chat_message_count`) are updated on every new message to avoid expensive aggregation queries on the chat list page.
+- `chat_active_session_id` is denormalized to avoid a JOIN with sessions on every incoming message check.
+- `chat_external_id` is the Meta conversation ID. Treated as an opaque string.
+
+---
+
+### 17. whatsapp_sessions
+
+**Purpose:** A session represents a single conversation interaction within a chat. When a patient sends a message after a period of inactivity, a new session is created. Sessions go through a lifecycle: `waiting` (grace period) -> `active` (AI responding) -> `resolved` (ended).
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `session_id` | UUID | Yes | `uuid()` | Primary key |
+| `session_chat_id` | UUID | Yes | -- | FK to `whatsapp_chats` |
+| `session_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `session_clinic_id` | UUID | Yes | -- | FK to `clinics`. Inherited from parent chat |
+| `session_status` | SessionStatus | Yes | `waiting` | Current lifecycle state |
+| `session_resolved_by` | SessionResolvedBy | No | `null` | How the session was resolved (null while active) |
+| `session_started_at` | DateTime | Yes | `now()` | When the session started |
+| `session_resolved_at` | DateTime | No | `null` | When the session was resolved |
+| `session_grace_deadline` | DateTime | No | `null` | When the grace period expires (BullMQ delayed job fires at this time) |
+| `session_taken_over_by_id` | UUID | No | `null` | FK to `users`. Staff member who took over from AI |
+| `session_taken_over_at` | DateTime | No | `null` | When the takeover happened |
+| `session_el_conversation_id` | String | No | `null` | Current ElevenLabs conversation ID |
+| `session_el_prev_conversation_ids` | String[] | Yes | `[]` | Previous conversation IDs (after reconnects) |
+| `session_el_conversation_created` | DateTime | No | `null` | When the ElevenLabs conversation was created |
+| `session_el_last_interaction` | DateTime | No | `null` | Last message exchange with ElevenLabs |
+| `session_el_cost` | Decimal | No | `null` | ElevenLabs cost for this session (fetched async) |
+| `session_ref_code` | String | No | `null` | Operator request REF code (e.g., `R-AB2X`) |
+| `session_awaiting_operator` | Boolean | Yes | `false` | True when waiting for doctor response. Prevents AI from auto-resolving |
+| `session_message_count` | Int | Yes | `0` | Messages in this session |
+| `session_llm_summary` | String | No | `null` | AI-generated session summary |
+| `session_sentiment` | Sentiment | No | `null` | AI-detected sentiment |
+| `session_categories` | String[] | Yes | `[]` | AI-generated categories |
+| `session_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `session_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `session_id` | PK lookup |
+| `idx_sessions_chat_status` | `(session_chat_id, session_status)` | Find active session for a chat (every incoming message) |
+| `idx_sessions_status_grace` | `(session_status, session_grace_deadline)` | Grace period expiry sweep |
+| `idx_sessions_tenant_status` | `(session_tenant_id, session_status)` | List active sessions for a tenant |
+| `idx_sessions_clinic_status` | `(session_clinic_id, session_status)` | List active sessions for a clinic |
+| `idx_sessions_status_updated` | `(session_status, session_updated_at)` | Inactivity sweep (resolve sessions idle > 2 hours) |
+| `idx_sessions_ref_tenant` | `(session_ref_code, session_tenant_id)` | Operator response matching: find session by REF code |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `session_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `session_clinic_id` | Assigned clinic |
+| belongs_to | whatsapp_chats | `session_chat_id` | Parent chat (cascade delete) |
+| belongs_to | users (TakenOverBy) | `session_taken_over_by_id` | Staff who took over |
+| has_many | whatsapp_messages | -- | Messages in this session |
+| has_many | operator_requests | -- | Operator requests in this session |
+| has_many | appointments | -- | Appointments booked during this session |
+| has_many | leads | -- | Leads generated from this session |
+
+**Design decisions:**
+- This is the most index-heavy table because sessions are queried from multiple angles: by chat (incoming message routing), by status (sweeps), by tenant/clinic (dashboard), by REF code (operator responses).
+- `session_el_prev_conversation_ids` tracks previous ElevenLabs conversations when WebSocket reconnections happen (chat continuity feature). Stored as an array on the session rather than a separate table because the list is short and always loaded with the session.
+- `session_awaiting_operator` is a boolean flag that prevents the inactivity sweep from resolving a session while the doctor has not yet responded.
+
+---
+
+### 18. whatsapp_messages
+
+**Purpose:** Individual messages within a WhatsApp or Instagram conversation. Each message belongs to a chat and optionally to a session. Message text is **encrypted at rest** (AES-256-GCM).
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `msg_id` | UUID | Yes | `uuid()` | Primary key |
+| `msg_chat_id` | UUID | Yes | -- | FK to `whatsapp_chats` |
+| `msg_session_id` | UUID | No | `null` | FK to `whatsapp_sessions`. Null for messages outside a session |
+| `msg_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `msg_external_id` | String | No | `null` | Provider message ID (Meta) for deduplication |
+| `msg_sender` | MessageSender | Yes | -- | `contact`, `ai`, `human`, or `system` |
+| `msg_sender_name` | String | Yes | `""` | Display name of the sender |
+| `msg_sender_user_id` | UUID | No | `null` | FK to `users`. Populated when `sender = 'human'` |
+| `msg_text` | String | Yes | -- | **Encrypted.** AES-256-GCM via `MESSAGE_ENCRYPTION_KEY`. Stored as base64(iv + authTag + ciphertext) |
+| `msg_media_type` | String | No | `null` | MIME-like type (e.g., `imageMessage`, `audioMessage`, `documentMessage`). Not encrypted |
+| `msg_media_key` | String | No | `null` | MinIO object key for media files. Not encrypted (key is opaque, file is SSE-encrypted in MinIO) |
+| `msg_ad_context` | Json | No | `null` | Ad attribution: `{ad: {title, body, source_url}, source, app}` |
+| `msg_sent_via_bridge` | Boolean | Yes | `false` | Whether the message was sent through Meta Business API |
+| `msg_quoted_text` | String | No | `null` | **Encrypted.** Text of the quoted/replied-to message. Same encryption as `msg_text` |
+| `msg_created_at` | DateTime | Yes | `now()` | Message timestamp |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `msg_id` | PK lookup |
+| `idx_msgs_chat_date` | `(msg_chat_id, msg_created_at)` | Load messages for a chat (ascending, paginated) |
+| `idx_msgs_session_date` | `(msg_session_id, msg_created_at)` | Load messages for a session |
+| `idx_msgs_tenant_date` | `(msg_tenant_id, msg_created_at DESC)` | Message listing/export |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `msg_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | whatsapp_chats | `msg_chat_id` | Parent chat (cascade delete) |
+| belongs_to | whatsapp_sessions | `msg_session_id` | Parent session (optional) |
+| belongs_to | users | `msg_sender_user_id` | Human sender (when `sender = 'human'`) |
+
+**Design decisions:**
+- **Message text is encrypted at rest.** `msg_text` and `msg_quoted_text` are AES-256-GCM encrypted using `MESSAGE_ENCRYPTION_KEY` (32-byte hex env var). Application encrypts before write, decrypts on read. Database and backups contain only opaque ciphertext.
+- **No full-text search on message content.** Encrypted text cannot be searched at the SQL level. With 7-day message retention (`clinic_message_retention_days`), deep search over history is not needed.
+- **Metadata is NOT encrypted:** `msg_sender`, `msg_media_type`, `msg_created_at` remain in plaintext for filtering, sorting, and indexing.
+- No `msg_updated_at` column. Messages are immutable once created.
+- `msg_media_key` stores the MinIO object key. Media files are SSE-encrypted in MinIO separately.
+- `msg_ad_context` captures WhatsApp ad attribution data. JSONB because the structure comes from Meta and may evolve.
+- `msg_session_id` is nullable because messages can arrive between sessions.
+- **Auto-deletion:** BullMQ job `whatsapp:message-cleanup` runs daily, deletes messages older than `clinic.clinic_message_retention_days` (default 7). Also removes associated MinIO media files.
+
+---
+
+### 19. ~~whatsapp_contact_profiles~~ — REMOVED
+
+> **This table has been removed.** Replaced by the `patients` table (#36). All contact profile data (phone, name, tags, AI summary, language, interaction stats) now lives on the Patient model. See [19-PATIENTS.md](19-PATIENTS.md) for migration details.
+
+---
+
+### 20. operator_requests
+
+**Purpose:** Tracks operator-in-the-loop requests. The AI forwards a message (text, media, or both) to a doctor/operator for review. The doctor responds via WhatsApp with the REF code. Media is optional — requests can be text-only (e.g., forwarding a patient question) or include photos/videos.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `opreq_id` | UUID | Yes | `uuid()` | Primary key |
+| `opreq_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `opreq_clinic_id` | UUID | Yes | -- | FK to `clinics` |
+| `opreq_session_id` | UUID | Yes | -- | FK to `whatsapp_sessions` |
+| `opreq_chat_id` | UUID | Yes | -- | FK to `whatsapp_chats` |
+| `opreq_ref_code` | String | Yes | -- | Reference code (e.g., `R-AB2X`). Unique per tenant |
+| `opreq_request_type` | String | Yes | `"general"` | Type: `general`, `photo_review`, `conversation_forward`, or custom |
+| `opreq_request_message` | String | No | `null` | **Encrypted.** Text/summary forwarded to the doctor. AES-256-GCM via `MESSAGE_ENCRYPTION_KEY` |
+| `opreq_status` | OperatorRequestStatus | Yes | `pending` | `pending` → `responded` / `expired` / `cancelled` |
+| `opreq_forwarded_media_types` | String[] | Yes | `[]` | Types of media forwarded. Empty for text-only requests |
+| `opreq_forwarded_count` | Int | Yes | `0` | Number of media items successfully forwarded. 0 for text-only |
+| `opreq_failed_count` | Int | Yes | `0` | Number of media items that failed to forward |
+| `opreq_forwarded_at` | DateTime | Yes | `now()` | When request was forwarded to doctor |
+| `opreq_forwarded_to_phone` | String | Yes | -- | Doctor's phone number |
+| `opreq_operator_response` | String | No | `null` | **Encrypted.** Doctor's reply text. AES-256-GCM via `MESSAGE_ENCRYPTION_KEY` |
+| `opreq_response_media_type` | String | No | `null` | Media type if doctor replied with a file/image |
+| `opreq_response_message_id` | String | No | `null` | Provider message ID of the doctor's reply |
+| `opreq_responded_at` | DateTime | No | `null` | When the doctor responded |
+| `opreq_patient_message_ids` | String[] | Yes | `[]` | Provider message IDs of patient messages that were forwarded |
+| `opreq_expires_at` | DateTime | Yes | -- | When this request expires if unanswered |
+| `opreq_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `opreq_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `opreq_id` | PK lookup |
+| Unique | `(opreq_tenant_id, opreq_ref_code)` | REF code uniqueness within a tenant |
+| `idx_opreqs_session_status` | `(opreq_session_id, opreq_status)` | Find pending request for a session |
+| `idx_opreqs_status_expires` | `(opreq_status, opreq_expires_at)` | Expiry sweep (BullMQ every 15 min) |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `opreq_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `opreq_clinic_id` | Assigned clinic |
+| belongs_to | whatsapp_sessions | `opreq_session_id` | Session that initiated the request |
+| belongs_to | whatsapp_chats | `opreq_chat_id` | Chat the patient is in |
+
+**Design decisions:**
+- **Generalized for any request type.** `opreq_request_type` defaults to `general`. Photo review (`photo_review`) and conversation forwarding (`conversation_forward`) are specific types. Media fields are empty/zero for text-only requests.
+- **Text fields encrypted.** `opreq_request_message` and `opreq_operator_response` contain patient-related medical/pricing info. Encrypted with `MESSAGE_ENCRYPTION_KEY` (same key as chat messages).
+- `opreq_clinic_id` is required. The request always belongs to a clinic (inherited from the session's clinic).
+- REF code format: `{prefix}-{4 alphanumeric}` (e.g., `R-AB2X`). Unique per tenant. Prefix configurable per clinic.
+- `opreq_forwarded_media_types` is an array tracking each forwarded media item's type. Empty array = text-only request.
+- `opreq_patient_message_ids` stores provider message IDs for media retrieval. Empty for text-only requests.
+
+---
+
+### 21. appointments
+
+**Purpose:** The source of truth for all appointments. Booked via AI (WhatsApp, voice call), manually by staff from the dashboard, or as walk-ins. Google Calendar is an optional sync target — not the source of truth.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `appt_id` | UUID | Yes | `uuid()` | Primary key |
+| `appt_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `appt_clinic_id` | UUID | Yes | -- | FK to `clinics` |
+| `appt_patient_id` | UUID | Yes | -- | FK to `patients`. Every appointment belongs to a patient |
+| `appt_doctor_id` | UUID | No | `null` | FK to `users` (doctor role). Which doctor performs the treatment |
+| `appt_treatment_id` | UUID | No | `null` | FK to `treatments`. What treatment this is for |
+| `appt_treatment_plan_item_id` | UUID | No | `null` | FK to `treatment_plan_items`. Which plan item (`tpitem_id`), if part of a plan |
+| `appt_chat_id` | UUID | No | `null` | FK to `whatsapp_chats`. Null for voice, dashboard, walk-in |
+| `appt_session_id` | UUID | No | `null` | FK to `whatsapp_sessions`. Null for voice, dashboard, walk-in |
+| `appt_google_event_id` | String | No | `null` | Google Calendar event ID. Null if Google Calendar not connected or not synced |
+| `appt_patient_name` | String | Yes | -- | Patient name (denormalized for list display) |
+| `appt_patient_phone` | String | Yes | -- | Patient phone (denormalized) |
+| `appt_start_time` | DateTime | Yes | -- | Appointment start time |
+| `appt_end_time` | DateTime | Yes | -- | Appointment end time |
+| `appt_duration_minutes` | Int | Yes | -- | Duration in minutes |
+| `appt_type` | AppointmentType | Yes | `appointment` | `appointment`, `walk_in`, `follow_up`, `consultation` |
+| `appt_status` | AppointmentStatus | Yes | `scheduled` | `scheduled`, `confirmed`, `in_progress`, `completed`, `cancelled`, `no_show` |
+| `appt_source` | AppointmentSource | Yes | `dashboard` | `whatsapp`, `voice_call`, `dashboard`, `walk_in` |
+| `appt_notes` | String | Yes | `""` | Appointment notes |
+| `appt_conversation_id` | String | No | `null` | ElevenLabs conversation ID (for AI-booked) |
+| `appt_cancelled_at` | DateTime | No | `null` | When the appointment was cancelled |
+| `appt_completed_at` | DateTime | No | `null` | When the appointment was marked completed |
+| `appt_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `appt_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `appt_id` | PK lookup |
+| `idx_appts_tenant_start` | `(appt_tenant_id, appt_start_time)` | Appointment list sorted by date |
+| `idx_appts_clinic_start` | `(appt_clinic_id, appt_start_time)` | Clinic-scoped appointment list |
+| `idx_appts_patient_start` | `(appt_patient_id, appt_start_time)` | Patient appointment history (timeline) |
+| `idx_appts_doctor_start` | `(appt_doctor_id, appt_start_time)` | Doctor's schedule |
+| `idx_appts_tenant_status` | `(appt_tenant_id, appt_status)` | Filter by status |
+| `idx_appts_google_event` | `(appt_google_event_id)` | Google Calendar sync lookup. Partial index on non-null values |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `appt_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `appt_clinic_id` | Which clinic's calendar |
+| belongs_to | patients | `appt_patient_id` | The patient |
+| belongs_to | users (doctor) | `appt_doctor_id` | Assigned doctor |
+| belongs_to | treatments | `appt_treatment_id` | Treatment type |
+| belongs_to | treatment_plan_items | `appt_treatment_plan_item_id` | Plan item (if part of a plan) |
+| belongs_to | whatsapp_chats | `appt_chat_id` | Source chat (nullable) |
+| belongs_to | whatsapp_sessions | `appt_session_id` | Source session (nullable) |
+
+**Design decisions:**
+- **Our system is the source of truth.** Appointments are created and managed here. Google Calendar is an optional integration — if connected, appointments are synced to Google Calendar. If not connected, appointments still work fully.
+- `appt_google_event_id` is nullable. Walk-ins, manual bookings, and clinics without Google Calendar have no event ID. When Google Calendar is connected, the event ID is stored after sync for two-way updates.
+- `appt_patient_id` is required. Every appointment belongs to a patient. The patient is resolved by phone number (for AI bookings) or selected from the dashboard (for manual bookings).
+- `appt_doctor_id` is nullable. Some appointments don't have a specific doctor (e.g., general consultation at a small clinic where any available doctor sees the patient).
+- `appt_treatment_id` is nullable. Consultations and walk-ins may not have a specific treatment.
+- `appt_treatment_plan_item_id` links the appointment to a specific step in a treatment plan. When the appointment completes, the plan item status updates to `completed`.
+- `appt_patient_name` and `appt_patient_phone` are denormalized from the patient record for list display without JOIN.
+- `appt_completed_at` added to track when a visit actually finished (separate from `updated_at` which changes on any edit).
+- The old unique constraint on `(google_event_id, tenant_id)` is replaced by a non-unique index since `google_event_id` is now nullable.
+
+---
+
+### 22. appointment_validation_batches
+
+**Purpose:** A batch of outbound calls to validate upcoming appointments. Staff uploads a CSV of appointments, the system calls each patient to confirm, cancel, or reschedule.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `batch_id` | UUID | Yes | `uuid()` | Primary key |
+| `batch_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `batch_clinic_id` | UUID | Yes | -- | FK to `clinics`. Which branch runs this validation |
+| `batch_created_by_id` | UUID | Yes | -- | FK to `users`. Who created this batch |
+| `batch_name` | String | Yes | -- | Batch name (e.g., "Monday Appointments") |
+| `batch_status` | BatchStatus | Yes | `draft` | Current lifecycle state |
+| `batch_el_batch_id` | String | No | `null` | ElevenLabs batch call ID |
+| `batch_agent_id` | UUID | No | `null` | FK to `agents`. Agent used for validation calls |
+| `batch_phone_id` | UUID | No | `null` | FK to `phone_numbers`. Outbound phone number |
+| `batch_column_mapping` | Json | Yes | -- | Maps CSV columns to fields: `{patient_name, patient_phone, appointment_date, ...}` |
+| `batch_call_schedule` | Json | Yes | -- | Call timing: `{call_date, call_start_time, call_end_time, max_concurrent, ...}` |
+| `batch_stats` | Json | Yes | `"{}"` | Aggregated stats (denormalized for dashboard) |
+| `batch_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `batch_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `batch_id` | PK lookup |
+| `idx_batches_tenant_date` | `(batch_tenant_id, batch_created_at DESC)` | Paginated batch list |
+| `idx_batches_el` | `batch_el_batch_id` | Resolve ElevenLabs callbacks |
+| `idx_batches_clinic` | `batch_clinic_id` | List batches for a clinic |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `batch_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `batch_clinic_id` | Scoped clinic |
+| belongs_to | users (CreatedBy) | `batch_created_by_id` | Creator |
+| belongs_to | agents | `batch_agent_id` | Validation agent |
+| belongs_to | phone_numbers | `batch_phone_id` | Outbound phone number |
+| has_many | appointment_validation_entries | -- | Individual entries |
+
+**Design decisions:**
+- `batch_column_mapping` is JSONB because the CSV column structure varies per upload.
+- `batch_stats` is denormalized (updated after each entry status change) to avoid expensive aggregation on the dashboard.
+- Lifecycle: `draft` -> `submitted` -> `in_progress` -> `completed` or `cancelled`.
+
+---
+
+### 23. appointment_validation_entries
+
+**Purpose:** Individual rows from the uploaded CSV. Each entry is one patient to call for appointment validation.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `bentry_id` | UUID | Yes | `uuid()` | Primary key |
+| `bentry_batch_id` | UUID | Yes | -- | FK to `appointment_validation_batches` |
+| `bentry_appointment_id` | UUID | No | `null` | FK to `appointments`. Linked when validation entry matches an appointment in our system |
+| `bentry_row_index` | Int | Yes | -- | Original row number from CSV (for display/ordering) |
+| `bentry_external_id` | String | Yes | `""` | External appointment ID from the source system |
+| `bentry_patient_name` | String | Yes | -- | Patient name |
+| `bentry_patient_phone` | String | Yes | -- | Patient phone (E.164) |
+| `bentry_appointment_date` | String | Yes | -- | Appointment date as string (from CSV, not parsed to DateTime) |
+| `bentry_appointment_time` | String | Yes | -- | Appointment time as string (from CSV) |
+| `bentry_doctor_name` | String | Yes | `""` | Doctor name (if available in CSV) |
+| `bentry_department` | String | Yes | `""` | Department (if available) |
+| `bentry_notes` | String | Yes | `""` | Additional notes |
+| `bentry_raw_data` | Json | Yes | `"{}"` | Complete original CSV row as JSON |
+| `bentry_call_status` | EntryCallStatus | Yes | `pending` | Call outcome status |
+| `bentry_attempts` | Int | Yes | `0` | Number of call attempts |
+| `bentry_conversation_id` | String | No | `null` | ElevenLabs conversation ID |
+| `bentry_validation_result` | ValidationResult | No | `null` | Outcome: `confirmed`, `cancelled`, `reschedule`, `unresolved` |
+| `bentry_reschedule_request` | String | No | `null` | Patient's preferred new time (if rescheduling) |
+| `bentry_patient_message` | String | No | `null` | Notable patient message during validation call |
+| `bentry_call_duration_secs` | Int | Yes | `0` | Call duration |
+| `bentry_called_at` | DateTime | No | `null` | When the call was made |
+| `bentry_result_at` | DateTime | No | `null` | When the validation result was recorded |
+| `bentry_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `bentry_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `bentry_id` | PK lookup |
+| `idx_bentries_batch_status` | `(bentry_batch_id, bentry_call_status)` | Dispatch pending entries, aggregate by status |
+| `idx_bentries_conversation` | `bentry_conversation_id` | Resolve ElevenLabs post-call webhook and tool callback |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | appointment_validation_batches | `bentry_batch_id` | Parent batch (cascade delete) |
+| belongs_to | appointments | `bentry_appointment_id` | Linked appointment in our system (optional) |
+
+**Design decisions:**
+- `bentry_appointment_id` enables closing the loop: when a patient confirms/cancels during the validation call, the system can auto-update the linked appointment's status (`confirmed`, `cancelled`). Nullable because CSV imports may contain appointments from external systems not in our database.
+- `bentry_appointment_date` and `bentry_appointment_time` are stored as strings, not DateTimes. The data comes from CSV and may have inconsistent formats. The AI agent receives the raw strings and interprets them.
+- `bentry_raw_data` preserves the complete original CSV row as JSONB. This ensures no data loss during column mapping and enables re-export.
+- Cascade delete from batch: deleting a batch removes all its entries.
+
+---
+
+### 24. billing_events
+
+**Purpose:** Individual billing events (charges, subscriptions, top-ups, refunds) for usage tracking. Each voice call generates a `call_charge` event based on duration.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `billing_id` | UUID | Yes | `uuid()` | Primary key |
+| `billing_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `billing_clinic_id` | UUID | No | `null` | FK to `clinics`. Which branch generated this charge. Null for tenant-level events (subscription, top_up) |
+| `billing_type` | BillingEventType | Yes | -- | `call_charge`, `subscription`, `top_up`, or `refund` |
+| `billing_amount` | Decimal | Yes | -- | Amount in TRY |
+| `billing_currency` | String | Yes | `"TRY"` | Currency code |
+| `billing_call_id` | UUID | No | `null` | FK to `calls`. Non-null for `call_charge` events |
+| `billing_description` | String | Yes | `""` | Human-readable description |
+| `billing_created_at` | DateTime | Yes | `now()` | Event timestamp |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `billing_id` | PK lookup |
+| `idx_billing_tenant_date` | `(billing_tenant_id, billing_created_at DESC)` | Billing history list |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `billing_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `billing_clinic_id` | Source clinic (optional) |
+| belongs_to | calls | `billing_call_id` | Associated call (for call charges) |
+
+**Design decisions:**
+- No `billing_updated_at`. Billing events are immutable once created.
+- `billing_clinic_id` enables per-clinic cost breakdown (`GROUP BY billing_clinic_id`). Null for tenant-level events like subscription payments and top-ups. Populated for call charges (copied from the call's clinic).
+- `Decimal` for `billing_amount` to avoid floating-point rounding.
+- Call charges are calculated at 1.5 TRY per minute.
+
+---
+
+### 25. payments
+
+**Purpose:** Tenant subscription payments recorded by staff. Tracks who paid, how much, for which plan, and the billing period covered.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `payment_id` | UUID | Yes | `uuid()` | Primary key |
+| `payment_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `payment_type` | PaymentType | Yes | `subscription` | `subscription` or `top_up` |
+| `payment_plan_slug` | String | Yes | -- | Plan slug at time of payment (denormalized) |
+| `payment_plan_name` | String | Yes | -- | Plan name at time of payment (denormalized) |
+| `payment_amount` | Decimal | Yes | -- | Amount paid in TRY |
+| `payment_extra_minutes` | Int | Yes | `0` | Extra call minutes purchased (for top-ups) |
+| `payment_period_start` | DateTime | Yes | -- | Start of the billing period this payment covers |
+| `payment_period_end` | DateTime | Yes | -- | End of the billing period |
+| `payment_method` | PaymentMethod | Yes | `cash` | How the payment was made |
+| `payment_notes` | String | Yes | `""` | Staff notes |
+| `payment_recorded_by_id` | UUID | Yes | -- | FK to `users`. Staff member who recorded the payment |
+| `payment_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `payment_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `payment_id` | PK lookup |
+| `idx_payments_tenant` | `payment_tenant_id` | List all payments for a tenant |
+| `idx_payments_tenant_period` | `(payment_tenant_id, payment_period_end DESC)` | Find active/latest billing period |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `payment_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | users (RecordedBy) | `payment_recorded_by_id` | Staff who recorded the payment |
+| has_many | billing_period_snapshots | -- | Usage snapshots for this period |
+| has_many | billing_alerts | -- | Alerts generated during this period |
+
+**Design decisions:**
+- `payment_plan_slug` and `payment_plan_name` are denormalized from the `plans` table at time of payment. This ensures the payment record remains accurate even if the plan is later modified.
+- `payment_period_start` and `payment_period_end` define the billing window. Usage is tracked within this window.
+
+---
+
+### 26. billing_period_snapshots
+
+**Purpose:** Snapshot of actual usage during a billing period. Created by a daily BullMQ job that checks for expired periods and captures final usage metrics.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `snapshot_id` | UUID | Yes | `uuid()` | Primary key |
+| `snapshot_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `snapshot_payment_id` | UUID | Yes | -- | FK to `payments`. Which payment/period this snapshot covers |
+| `snapshot_plan_id` | UUID | No | `null` | FK to `plans`. Plan at time of snapshot (for limit comparison) |
+| `snapshot_period_start` | DateTime | Yes | -- | Start of the billing period |
+| `snapshot_period_end` | DateTime | Yes | -- | End of the billing period |
+| `snapshot_total_calls` | Int | Yes | `0` | Total voice calls |
+| `snapshot_inbound_calls` | Int | Yes | `0` | Inbound call count |
+| `snapshot_inbound_minutes` | Decimal | Yes | `0` | Inbound call minutes |
+| `snapshot_outbound_calls` | Int | Yes | `0` | Outbound call count |
+| `snapshot_outbound_minutes` | Decimal | Yes | `0` | Outbound call minutes |
+| `snapshot_total_charges` | Decimal | Yes | `0` | Total TRY charges |
+| `snapshot_wa_billable_chats` | Int | Yes | `0` | WhatsApp billable chat count |
+| `snapshot_wa_total_sessions` | Int | Yes | `0` | Total WhatsApp sessions |
+| `snapshot_wa_total_messages` | Int | Yes | `0` | Total WhatsApp messages |
+| `snapshot_wa_ai_messages` | Int | Yes | `0` | AI-sent WhatsApp messages |
+| `snapshot_wa_el_cost` | Decimal | Yes | `0` | ElevenLabs cost for WhatsApp |
+| `snapshot_wa_stt_count` | Int | Yes | `0` | Speech-to-text transcription count |
+| `snapshot_wa_stt_seconds` | Decimal | Yes | `0` | Speech-to-text total seconds |
+| `snapshot_created_at` | DateTime | Yes | `now()` | Snapshot timestamp |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `snapshot_id` | PK lookup |
+| `idx_snapshots_tenant_period` | `(snapshot_tenant_id, snapshot_period_start DESC)` | Historical usage lookup |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `snapshot_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | payments | `snapshot_payment_id` | Associated payment |
+| belongs_to | plans | `snapshot_plan_id` | Plan at time of snapshot |
+
+**Design decisions:**
+- No `snapshot_updated_at`. Snapshots are immutable once created.
+- `Decimal` for all minute and cost fields to avoid floating-point rounding.
+- `snapshot_plan_id` captures the plan at the time of the snapshot so that usage vs. limits can be compared historically even if the plan changes later.
+
+---
+
+### 27. billing_alerts
+
+**Purpose:** Tracks which billing alerts have been sent to prevent duplicates. Each combination of tenant + alert type + service + payment is unique.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `alert_id` | UUID | Yes | `uuid()` | Primary key |
+| `alert_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `alert_type` | AlertType | Yes | -- | `usage_75`, `usage_90`, `usage_100`, or `period_expiring` |
+| `alert_service` | AlertService | Yes | -- | Which service/metric triggered the alert |
+| `alert_payment_id` | UUID | Yes | -- | FK to `payments`. Which billing period |
+| `alert_created_at` | DateTime | Yes | `now()` | When the alert was sent |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `alert_id` | PK lookup |
+| Unique | `(alert_tenant_id, alert_type, alert_service, alert_payment_id)` | Prevent sending the same alert twice |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `alert_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | payments | `alert_payment_id` | Billing period context |
+
+**Design decisions:**
+- The four-column unique constraint prevents duplicate alerts. The daily billing alert job checks this constraint before sending.
+- No `alert_updated_at`. Alerts are immutable.
+
+---
+
+### 28. stt_usages
+
+**Purpose:** Tracks speech-to-text usage for billing and analytics. One record per voice message transcription.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `stt_id` | UUID | Yes | `uuid()` | Primary key |
+| `stt_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `stt_clinic_id` | UUID | No | `null` | FK to `clinics`. Which branch generated this usage |
+| `stt_chat_id` | String | Yes | `""` | WhatsApp chat ID (informational, not an FK) |
+| `stt_message_id` | String | Yes | `""` | Message ID (informational) |
+| `stt_duration_seconds` | Decimal | Yes | -- | Audio duration in seconds |
+| `stt_character_count` | Int | Yes | -- | Characters in the transcribed text |
+| `stt_language` | String | Yes | `"tr"` | Transcription language |
+| `stt_created_at` | DateTime | Yes | `now()` | Transcription timestamp |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `stt_id` | PK lookup |
+| `idx_stt_tenant_date` | `(stt_tenant_id, stt_created_at DESC)` | Usage aggregation for billing |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `stt_tenant_id` | Parent tenant (cascade delete) |
+
+**Design decisions:**
+- `stt_chat_id` and `stt_message_id` are String fields, not FKs. They are informational references for debugging. No join needed.
+- No `stt_updated_at`. Usage records are immutable.
+
+---
+
+### 29. logs
+
+**Purpose:** Application logs stored in PostgreSQL for the admin dashboard. Only `info` level and above are persisted to the database (debug/trace stay in console/file). Written asynchronously in batches (max 100, flush every 5 seconds).
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `log_id` | UUID | Yes | `uuid()` | Primary key |
+| `log_level` | String | Yes | -- | Log level: `fatal`, `error`, `warn`, `info` |
+| `log_message` | String | Yes | -- | Human-readable log message |
+| `log_service` | String | Yes | `"api"` | Which service/module (e.g., `"whatsapp-agent"`, `"billing"`, `"calendar.tools"`) |
+| `log_meta` | Json | Yes | `"{}"` | Structured data payload |
+| `log_request_id` | String | No | `null` | Correlation ID (traces a request across services/queues) |
+| `log_tenant_id` | String | No | `null` | Tenant context (not an FK -- logs may outlive tenants) |
+| `log_clinic_id` | String | No | `null` | Clinic context |
+| `log_user_id` | String | No | `null` | User context |
+| `log_timestamp` | DateTime | Yes | `now()` | Log event timestamp |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `log_id` | PK lookup |
+| `idx_logs_level` | `log_level` | Filter by level |
+| `idx_logs_timestamp` | `log_timestamp` | Time-range queries |
+| `idx_logs_level_timestamp` | `(log_level, log_timestamp DESC)` | Filter by level + time range (admin dashboard) |
+| `idx_logs_tenant_timestamp` | `(log_tenant_id, log_timestamp DESC)` | Tenant-scoped log viewing |
+| `idx_logs_request` | `log_request_id` | Trace all logs for a single request |
+| `idx_logs_service_timestamp` | `(log_service, log_timestamp DESC)` | Filter by service |
+
+**Relations:** None. Log columns like `log_tenant_id` are strings, not FKs, because logs may need to survive tenant deletion and should never cause cascading failures.
+
+**Design decisions:**
+- Six indexes -- logs are the most-read table in the admin panel and need fast filtering across multiple dimensions.
+- No foreign keys. Logs are a standalone observability layer. Tenant/user/clinic IDs are strings for informational purposes.
+- Cleanup: BullMQ job runs daily at 3am, deletes logs older than configurable retention (default 30 days).
+- Written via async batched writer to avoid impacting request performance.
+
+---
+
+### 30. audit_logs
+
+**Purpose:** Immutable audit trail tracking who did what, when, and what changed. Separate from application logs. Never auto-deleted. Used for compliance (KVKK), accountability, and forensics.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `audit_id` | UUID | Yes | `uuid()` | Primary key |
+| `audit_tenant_id` | String | No | `null` | Tenant context. Null for platform actions (e.g., sales creating tenant) |
+| `audit_clinic_id` | String | No | `null` | Clinic context. Null for tenant-level actions |
+| `audit_user_id` | String | No | `null` | Acting user. Null for system actions (cron, AI) |
+| `audit_user_email` | String | No | `null` | Denormalized email -- survives user deletion |
+| `audit_user_role` | String | No | `null` | User's role at the time of the action |
+| `audit_action` | String | Yes | -- | Action identifier (e.g., `"clinic.settings.updated"`, `"appointment.created"`) |
+| `audit_entity` | String | Yes | -- | Entity type (e.g., `"Tenant"`, `"Appointment"`, `"User"`) |
+| `audit_entity_id` | String | Yes | -- | ID of the affected record |
+| `audit_changes` | Json | No | `null` | Before/after diff: `{field: {old: x, new: y}}`. Null for non-update actions |
+| `audit_metadata` | Json | No | `null` | Extra context: `{ip, userAgent, requestId, reason}` |
+| `audit_created_at` | DateTime | Yes | `now()` | Action timestamp |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `audit_id` | PK lookup |
+| `idx_audit_tenant_date` | `(audit_tenant_id, audit_created_at DESC)` | Tenant audit trail |
+| `idx_audit_clinic_date` | `(audit_clinic_id, audit_created_at DESC)` | Clinic audit trail |
+| `idx_audit_entity` | `(audit_entity, audit_entity_id)` | History of a specific record |
+| `idx_audit_user_date` | `(audit_user_id, audit_created_at DESC)` | All actions by a specific user |
+| `idx_audit_action_date` | `(audit_action, audit_created_at DESC)` | Filter by action type |
+
+**Relations:** None. Like logs, audit entries use string IDs rather than FKs to ensure they survive entity deletion.
+
+**Design decisions:**
+- No `audit_updated_at`. Audit logs are append-only and immutable.
+- `audit_user_email` and `audit_user_role` are denormalized so the audit trail remains meaningful even after users are deleted.
+- `audit_changes` captures the diff as `{field: {old, new}}` for update actions. Null for creates, deletes, and non-mutation actions (like login).
+- Written synchronously (not batched) because audit events must not be lost.
+- Retention: never auto-deleted. For large tenants, old audit logs (>2 years) can be manually archived to MinIO.
+
+---
+
+### 31. tool_execution_logs
+
+**Purpose:** Tracks every AI tool execution (e.g., `check_availability`, `reserve_slot`, `forward_to_operator`) for observability and analytics. Written fire-and-forget by the ToolRegistryService.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `toollog_id` | UUID | Yes | `uuid()` | Primary key |
+| `toollog_tenant_id` | String | Yes | -- | Tenant context |
+| `toollog_clinic_id` | String | No | `null` | Clinic context |
+| `toollog_tool_name` | String | Yes | -- | Tool name (e.g., `"check_availability"`) |
+| `toollog_channel` | String | Yes | -- | Channel: `"whatsapp"`, `"voice_call"`, `"instagram"`, `"test_chat"` |
+| `toollog_patient_phone` | String | Yes | `""` | Patient phone number |
+| `toollog_conversation_id` | String | No | `null` | ElevenLabs conversation ID |
+| `toollog_parameters` | Json | Yes | `"{}"` | Parameters passed to the tool |
+| `toollog_result` | Json | Yes | `"{}"` | Tool execution result |
+| `toollog_is_error` | Boolean | Yes | `false` | Whether the execution resulted in an error |
+| `toollog_duration_ms` | Int | Yes | `0` | Execution time in milliseconds |
+| `toollog_created_at` | DateTime | Yes | `now()` | Execution timestamp |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `toollog_id` | PK lookup |
+| `idx_toollog_tenant_date` | `(toollog_tenant_id, toollog_created_at DESC)` | Tenant-scoped tool log list |
+| `idx_toollog_tool_date` | `(toollog_tool_name, toollog_created_at DESC)` | Filter by tool name |
+| `idx_toollog_conversation` | `toollog_conversation_id` | Find all tool calls in a conversation |
+
+**Relations:** None. Uses string IDs for tenant reference to avoid cascading issues.
+
+**Design decisions:**
+- No foreign keys. Like logs and audit logs, this is an observability table.
+- Written fire-and-forget with `.catch(() => {})` to never impact tool execution performance.
+- Cleanup: BullMQ job deletes logs older than 30 days (or per-tenant retention policy).
+
+---
+
+### 32. migrations
+
+**Purpose:** Tracks custom data migration runs (not Prisma schema migrations -- those are managed by `prisma migrate`). Used for one-time data transformations, backfills, and cross-system imports.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `migration_id` | UUID | Yes | `uuid()` | Primary key |
+| `migration_name` | String | Yes (unique) | -- | Migration identifier (e.g., `"backfill-clinic-slugs"`) |
+| `migration_ran_at` | DateTime | Yes | -- | When the migration ran |
+| `migration_duration_ms` | Int | Yes | -- | How long it took in milliseconds |
+| `migration_status` | MigrationStatus | Yes | -- | `success` or `failed` |
+| `migration_error` | String | No | `null` | Error message if failed |
+| `migration_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `migration_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `migration_id` | PK lookup |
+| Unique | `migration_name` | Prevent running the same migration twice |
+
+**Relations:** None.
+
+**Design decisions:**
+- The unique constraint on `migration_name` ensures idempotency. A migration script checks this table before running.
+- This table is for application-level data migrations only. Schema migrations are tracked by Prisma's `_prisma_migrations` table.
+
+---
+
+### 33. transcriptions
+
+> **TODO:** Revisit overlap with `call_details` table (which also stores transcript + summary). These tables may serve as a processing pipeline/staging area, or they may be consolidated into call_details.
+
+**Purpose:** Stores post-call transcriptions received from ElevenLabs webhooks. Each transcription has a processing pipeline: received -> summarized -> notified.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `tx_id` | UUID | Yes | `uuid()` | Primary key |
+| `tx_conversation_id` | String | Yes (unique) | -- | ElevenLabs conversation ID |
+| `tx_agent_id` | String | Yes | -- | ElevenLabs agent ID |
+| `tx_agent_name` | String | No | `null` | Agent name (denormalized for display) |
+| `tx_user_id` | String | No | `null` | User/caller identifier from ElevenLabs |
+| `tx_event_type` | String | Yes | `"post_call_transcription"` | Event type |
+| `tx_event_timestamp` | Int | No | `null` | Unix timestamp from ElevenLabs |
+| `tx_status` | String | Yes | `"done"` | ElevenLabs-reported status |
+| `tx_transcript` | Json | Yes | `"[]"` | Array of transcript entries `[{role, message, timestamp}]` |
+| `tx_metadata` | Json | No | `null` | ElevenLabs metadata payload |
+| `tx_analysis` | Json | No | `null` | ElevenLabs analysis payload |
+| `tx_processing_status` | TranscriptionProcessingStatus | Yes | `pending` | Pipeline stage |
+| `tx_processing_error` | String | No | `null` | Error message if processing failed |
+| `tx_raw_payload` | Json | No | `null` | Complete raw webhook payload (for debugging) |
+| `tx_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `tx_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `tx_id` | PK lookup |
+| Unique | `tx_conversation_id` | One transcription per conversation |
+| `idx_tx_agent` | `tx_agent_id` | Filter by agent |
+| `idx_tx_user` | `tx_user_id` | Filter by caller |
+| `idx_tx_processing` | `tx_processing_status` | Find unprocessed transcriptions (BullMQ) |
+| `idx_tx_date` | `tx_created_at DESC` | Chronological listing |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| has_one | summaries | -- | AI-generated summary of this transcription |
+
+**Design decisions:**
+- `tx_transcript` is JSONB because the transcript is an array of objects with variable structure from ElevenLabs.
+- `tx_raw_payload` stores the complete webhook payload for debugging. Can be large but is rarely accessed.
+- The processing pipeline is: `pending` -> `summarizing` -> `summarized` -> `notified` (or `failed` at any step).
+
+---
+
+### 34. summaries
+
+> **TODO:** Same as transcriptions — revisit overlap with `call_details.detail_llm_summary`.
+
+**Purpose:** AI-generated summaries of call transcriptions. Created asynchronously by the summary generation pipeline.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `summary_id` | UUID | Yes | `uuid()` | Primary key |
+| `summary_transcription_id` | UUID | Yes (unique) | -- | FK to `transcriptions`. One-to-one |
+| `summary_conversation_id` | String | Yes | -- | ElevenLabs conversation ID (denormalized for direct lookup) |
+| `summary_text` | String | Yes | -- | Full summary text |
+| `summary_title` | String | No | `null` | Short title/headline |
+| `summary_key_points` | String[] | Yes | `[]` | Bullet-point key takeaways |
+| `summary_detected_intent` | String | No | `null` | AI-detected caller intent |
+| `summary_sentiment` | Sentiment | No | `null` | AI-detected sentiment |
+| `summary_ai_provider` | String | Yes | -- | Which AI provider generated this (`"openai"` or `"anthropic"`) |
+| `summary_ai_model` | String | No | `null` | Specific model used |
+| `summary_token_usage` | Json | No | `null` | Token usage: `{promptTokens, completionTokens, totalTokens}` |
+| `summary_notification_status` | NotificationDeliveryStatus | Yes | `pending` | Status of summary notification to staff |
+| `summary_notified_recipients` | Json | Yes | `"[]"` | Array of recipients who were notified |
+| `summary_language` | String | Yes | `"tr"` | Language of the summary |
+| `summary_created_at` | DateTime | Yes | `now()` | Summary generation timestamp |
+| `summary_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `summary_id` | PK lookup |
+| Unique | `summary_transcription_id` | One-to-one with transcriptions |
+| `idx_summary_conversation` | `summary_conversation_id` | Direct lookup by conversation |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | transcriptions | `summary_transcription_id` | Source transcription |
+
+**Design decisions:**
+- One-to-one with transcriptions via unique constraint.
+- `summary_ai_provider` and `summary_ai_model` track which AI generated the summary for cost tracking and quality comparison.
+- `summary_token_usage` is JSONB because the structure varies slightly between providers.
+- `summary_key_points` is a `String[]` array for easy rendering as bullet points.
+
+---
+
+### 35. ~~whatsapp_recipients~~ — REMOVED
+
+> **This table has been removed.** Legacy table with no tenant scoping. Notification recipients are now handled by `clinic_notification_phones` and `clinic_sms_phones` on the clinics table. WhatsApp group notifications can be reimplemented properly when needed.
+
+---
+
+## Clinic Management Tables
+
+> The following tables were added as part of the clinic management pivot.
+> Patient is the central entity. Treatment catalog, treatment plans, doctor profiles,
+> and before/after photos support the core clinic workflow.
+
+---
+
+### 36. patients
+
+**Purpose:** Central entity in the system. Every person who contacts or visits the clinic gets a Patient record. Replaces `whatsapp_contact_profiles` (#19). Auto-created on first AI contact (WhatsApp, voice call, Instagram). Enriched manually by staff from the dashboard.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `patient_id` | UUID | Yes | `uuid()` | Primary key |
+| `patient_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `patient_clinic_id` | UUID | No | `null` | FK to `clinics`. Primary clinic (nullable for unassigned) |
+| `patient_phone` | String | Yes | -- | Primary phone number (E.164) |
+| `patient_email` | String | No | `null` | Email address |
+| `patient_first_name` | String | Yes | `""` | First name |
+| `patient_last_name` | String | Yes | `""` | Last name |
+| `patient_display_name` | String | Yes | `""` | Auto-built from first+last, or from WhatsApp profile name |
+| `patient_date_of_birth` | DateTime | No | `null` | Date of birth |
+| `patient_gender` | String | No | `null` | `male`, `female`, `other` |
+| `patient_id_number` | String | No | `null` | **Encrypted.** TC Kimlik No. AES-256-GCM via `PATIENT_PII_ENCRYPTION_KEY` |
+| `patient_blood_type` | String | No | `null` | Blood type (e.g., `A+`, `O-`) |
+| `patient_preferred_language` | String | Yes | `"tr"` | Preferred communication language |
+| `patient_source` | String | No | `null` | How the patient found the clinic: `whatsapp`, `voice_call`, `instagram`, `dashboard`, `walk_in`, `referral`, `campaign` |
+| `patient_source_detail` | String | No | `null` | Campaign name, referrer name, ad ID |
+| `patient_tags` | String[] | Yes | `[]` | Free-form tags for segmentation |
+| `patient_ai_summary` | String | Yes | `""` | **Encrypted.** AI-generated summary from conversations. AES-256-GCM via `PATIENT_SUMMARY_ENCRYPTION_KEY` |
+| `patient_is_active` | Boolean | Yes | `true` | Soft-disable. Inactive patients are hidden from lists |
+| `patient_first_contact_at` | DateTime | Yes | `now()` | First interaction timestamp |
+| `patient_last_contact_at` | DateTime | Yes | `now()` | Most recent interaction timestamp |
+| `patient_total_sessions` | Int | Yes | `0` | Denormalized WhatsApp session count |
+| `patient_total_appointments` | Int | Yes | `0` | Denormalized appointment count |
+| `patient_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `patient_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `patient_id` | PK lookup |
+| Unique | `(patient_tenant_id, patient_phone)` | One patient per phone per tenant |
+| `idx_patients_tenant_lastcontact` | `(patient_tenant_id, patient_last_contact_at DESC)` | Patient list sorted by recent activity |
+| `idx_patients_clinic` | `patient_clinic_id` | Patients by clinic |
+| `idx_patients_tenant_name` | `(patient_tenant_id, patient_last_name, patient_first_name)` | Name search |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `patient_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `patient_clinic_id` | Primary clinic |
+| has_one | patient_medical_histories | -- | Medical history / anamnesis |
+| has_many | treatment_plans | -- | Treatment plans for this patient |
+| has_many | appointments | -- | All appointments |
+| has_many | patient_photo_sets | -- | Before/after photos |
+| has_many | patient_documents | -- | Documents (consent, x-ray, etc.) |
+| has_many | patient_notes | -- | Staff notes |
+| has_many | whatsapp_chats | -- | WhatsApp/Instagram conversations |
+| has_many | operator_requests | -- | Via session → chat → patient |
+| has_many | leads | -- | Leads linked to this patient |
+
+**Design decisions:**
+- Replaces `whatsapp_contact_profiles`. All ContactProfile fields migrated here (see doc 19-PATIENTS.md Section 11).
+- `patient_phone` is the natural matching key. On first WhatsApp/voice contact, the system creates a Patient from the phone number.
+- `patient_display_name` is auto-built as `"{first_name} {last_name}"` on update, or initialized from the WhatsApp profile name on auto-creation.
+- `patient_source` is a free-form string (not enum) because clinics will add custom sources.
+- Denormalized counters (`total_sessions`, `total_appointments`) avoid expensive COUNT queries on patient list views.
+- **Two encryption keys for patient data:** `PATIENT_PII_ENCRYPTION_KEY` for national ID (TC Kimlik), `PATIENT_SUMMARY_ENCRYPTION_KEY` for AI summary. Separate from `MESSAGE_ENCRYPTION_KEY` to limit blast radius.
+
+---
+
+### 37. patient_medical_histories
+
+**Purpose:** Static anamnesis form for a patient. Background health info filled once during first consultation, updated occasionally. One-to-one with `patients`. Per-visit clinical records are in `examination_records` (#46).
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `history_id` | UUID | Yes | `uuid()` | Primary key |
+| `history_patient_id` | UUID | Yes (unique) | -- | FK to `patients`. One-to-one |
+| `history_allergies` | String | Yes | `""` | **Encrypted.** Known allergies as JSON string. AES-256-GCM via `PATIENT_PII_ENCRYPTION_KEY` |
+| `history_chronic_conditions` | String | Yes | `""` | **Encrypted.** Chronic conditions as JSON string. Same key |
+| `history_current_medications` | String | Yes | `""` | **Encrypted.** Current medications as JSON string. Same key |
+| `history_past_surgeries` | String | Yes | `""` | **Encrypted.** Description of past surgeries. Same key |
+| `history_pregnancy_status` | String | No | `null` | `not_applicable`, `not_pregnant`, `pregnant`, `unknown`. Not encrypted (non-identifying enum) |
+| `history_smoking` | Boolean | No | `null` | Whether the patient smokes. Not encrypted |
+| `history_alcohol` | Boolean | No | `null` | Whether the patient drinks alcohol. Not encrypted |
+| `history_notes` | String | Yes | `""` | **Encrypted.** Free-text medical notes. Same key |
+| `history_anamnesis_completed` | Boolean | Yes | `false` | Whether the anamnesis form has been filled |
+| `history_anamnesis_date` | DateTime | No | `null` | When the anamnesis was completed |
+| `history_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `history_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `history_id` | PK lookup |
+| Unique | `history_patient_id` | Enforce one-to-one with patients |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | patients | `history_patient_id` | Parent patient (cascade delete) |
+
+**Design decisions:**
+- Separate table (not JSONB on patient) because medical history is a distinct concern with its own access patterns, updated independently, and may grow with regulation-required fields.
+- **All text medical content is encrypted** with `PATIENT_PII_ENCRYPTION_KEY`. Allergies, conditions, medications, surgeries, and notes contain sensitive health data.
+- Array fields (`allergies`, `chronic_conditions`, `medications`) changed from `String[]` to encrypted `String`. The application stores them as JSON-serialized arrays, encrypted before write, decrypted and parsed on read. Encrypted content cannot use PostgreSQL array operations.
+- Boolean fields (`smoking`, `alcohol`) and enum fields (`pregnancy_status`) are NOT encrypted — they are non-identifying and needed for quick UI display.
+- `history_anamnesis_completed` flag lets the UI show "anamnesis pending" badges.
+- This is the **static background**. Per-visit clinical findings go in `examination_records` (#46).
+
+---
+
+### 38. patient_documents
+
+**Purpose:** Files attached to a patient record. Stored in MinIO, referenced by object key. Consent forms, X-rays, lab results, prescriptions, referral letters.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `doc_id` | UUID | Yes | `uuid()` | Primary key |
+| `doc_patient_id` | UUID | Yes | -- | FK to `patients` |
+| `doc_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `doc_clinic_id` | UUID | Yes | -- | FK to `clinics`. Which branch uploaded this |
+| `doc_appointment_id` | UUID | No | `null` | FK to `appointments`. Which visit this document belongs to |
+| `doc_type` | String | Yes | `"other"` | Document type: `consent_form`, `lab_result`, `x_ray`, `prescription`, `referral`, `other` |
+| `doc_name` | String | Yes | -- | Original file name |
+| `doc_media_key` | String | Yes | -- | MinIO object key: `{tenantId}/patients/{patientId}/documents/{docId}.{ext}` |
+| `doc_content_type` | String | Yes | -- | MIME type (e.g., `application/pdf`, `image/jpeg`) |
+| `doc_size_bytes` | Int | Yes | `0` | File size in bytes |
+| `doc_uploaded_by` | UUID | No | `null` | FK to `users`. Who uploaded the document |
+| `doc_notes` | String | Yes | `""` | **Encrypted.** Notes about the document. AES-256-GCM via `PATIENT_PII_ENCRYPTION_KEY` |
+| `doc_created_at` | DateTime | Yes | `now()` | Upload timestamp |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `doc_id` | PK lookup |
+| `idx_docs_patient_date` | `(doc_patient_id, doc_created_at DESC)` | Patient document list (most recent first) |
+| `idx_docs_tenant_type` | `(doc_tenant_id, doc_type)` | Filter by type across tenant |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | patients | `doc_patient_id` | Parent patient (cascade delete) |
+| belongs_to | tenants | `doc_tenant_id` | Parent tenant |
+| belongs_to | clinics | `doc_clinic_id` | Which clinic uploaded this |
+| belongs_to | appointments | `doc_appointment_id` | Which visit (optional) |
+| belongs_to | users | `doc_uploaded_by` | Uploader |
+
+**Design decisions:**
+- No `doc_updated_at`. Documents are immutable once uploaded. To replace a document, delete the old one and upload a new one.
+- `doc_appointment_id` links a document to a specific visit. Enables "show all documents from this appointment" on the examination record. Nullable — not all documents are visit-specific (e.g., general consent form).
+- `doc_notes` encrypted with `PATIENT_PII_ENCRYPTION_KEY` — may contain clinical observations about the document.
+- `doc_type` is a string, not a Prisma enum, because clinics may need custom document types.
+- File content is in MinIO. Database stores only the key. Served via signed URL (1hr TTL).
+- On KVKK deletion: both the DB record and MinIO object are removed.
+
+---
+
+### 39. patient_notes
+
+**Purpose:** Free-text notes added by staff to a patient record. Simple and lightweight — not a chat, just clinical or administrative observations.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `note_id` | UUID | Yes | `uuid()` | Primary key |
+| `note_patient_id` | UUID | Yes | -- | FK to `patients` |
+| `note_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `note_clinic_id` | UUID | Yes | -- | FK to `clinics`. Which branch |
+| `note_author_id` | UUID | Yes | -- | FK to `users`. Who wrote the note |
+| `note_text` | String | Yes | -- | **Encrypted.** Note content. AES-256-GCM via `PATIENT_PII_ENCRYPTION_KEY` |
+| `note_is_pinned` | Boolean | Yes | `false` | Pinned notes show at top of patient detail |
+| `note_created_at` | DateTime | Yes | `now()` | Creation timestamp |
+| `note_updated_at` | DateTime | Yes | auto | Automatically updated on edit |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `note_id` | PK lookup |
+| `idx_notes_patient_date` | `(note_patient_id, note_created_at DESC)` | Patient notes list (most recent first) |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | patients | `note_patient_id` | Parent patient (cascade delete) |
+| belongs_to | tenants | `note_tenant_id` | Parent tenant |
+| belongs_to | clinics | `note_clinic_id` | Which clinic |
+| belongs_to | users | `note_author_id` | Note author |
+
+**Design decisions:**
+- `note_text` encrypted with `PATIENT_PII_ENCRYPTION_KEY` — notes may contain clinical or personal observations.
+- Author is always required. Anonymous notes are not allowed.
+- Pinned notes are a simple boolean — no ordering among pinned notes (most recent first within pinned).
+- Notes are editable (has `updated_at`), but audit trail tracks changes via the `@Auditable()` interceptor.
+- No appointment link — clinical per-visit documentation goes in `examination_records` (#46). Notes are for general observations.
+
+---
+
+### 40. treatments
+
+**Purpose:** Service catalog for a clinic. Each treatment defines what the clinic offers: name, category, duration, price. Used in treatment plans and appointment booking.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `treatment_id` | UUID | Yes | `uuid()` | Primary key |
+| `treatment_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `treatment_clinic_id` | UUID | No | `null` | FK to `clinics`. Null = available at all clinics in the tenant |
+| `treatment_name` | String | Yes | -- | Treatment name (e.g., "Root Canal", "Botox") |
+| `treatment_category` | String | Yes | `""` | Category (e.g., "Implant", "Ortodonti", "Estetik") |
+| `treatment_description` | String | Yes | `""` | Description of the treatment |
+| `treatment_duration_minutes` | Int | Yes | `30` | Default appointment duration for this treatment |
+| `treatment_price` | Decimal | No | `null` | Base price. Null = price varies / not listed |
+| `treatment_currency` | String | Yes | `"TRY"` | Currency code |
+| `treatment_is_active` | Boolean | Yes | `true` | Soft-disable. Inactive treatments hidden from catalog |
+| `treatment_sort_order` | Int | Yes | `0` | Display ordering within category |
+| `treatment_recall_days` | Int | No | `null` | Days after completion to schedule a recall. Null = no recall. E.g., 180 for biannual cleaning |
+| `treatment_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `treatment_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `treatment_id` | PK lookup |
+| `idx_treatments_tenant_active` | `(treatment_tenant_id, treatment_is_active)` | Active treatment list |
+| `idx_treatments_tenant_category` | `(treatment_tenant_id, treatment_category)` | Filter by category |
+| `idx_treatments_clinic` | `treatment_clinic_id` | Clinic-scoped treatments |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `treatment_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `treatment_clinic_id` | Scoped clinic (optional) |
+| has_many | treatment_plan_items | -- | Plan items referencing this treatment |
+| has_many | appointments | -- | Appointments for this treatment |
+
+**Design decisions:**
+- `treatment_clinic_id` null means available at all clinics. Clinic-specific treatments (e.g., a treatment only offered at the Kadikoy branch) set the clinic FK.
+- `treatment_category` is a free-form string, not an enum. Clinics define their own categories.
+- `Decimal` for price to avoid floating-point currency issues.
+- `treatment_recall_days` supports P1 recall automation. E.g., dental cleaning = 180 days → auto-remind patient in 6 months.
+
+---
+
+### 41. treatment_plans
+
+**Purpose:** A multi-visit treatment plan for a specific patient. Contains ordered items, each linked to a treatment from the catalog and optionally to a booked appointment.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `tplan_id` | UUID | Yes | `uuid()` | Primary key |
+| `tplan_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `tplan_clinic_id` | UUID | Yes | -- | FK to `clinics` |
+| `tplan_patient_id` | UUID | Yes | -- | FK to `patients` |
+| `tplan_doctor_id` | UUID | No | `null` | FK to `users` (doctor role). Doctor managing this plan |
+| `tplan_name` | String | Yes | -- | Plan name (e.g., "Full Mouth Rehabilitation") |
+| `tplan_status` | TreatmentPlanStatus | Yes | `active` | `active`, `completed`, `cancelled` |
+| `tplan_notes` | String | Yes | `""` | **Encrypted.** Doctor notes about the plan. AES-256-GCM via `PATIENT_PII_ENCRYPTION_KEY` |
+| `tplan_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `tplan_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `tplan_id` | PK lookup |
+| `idx_tplans_patient_status` | `(tplan_patient_id, tplan_status)` | Patient's active/completed plans |
+| `idx_tplans_tenant_status` | `(tplan_tenant_id, tplan_status)` | Tenant-wide plan overview |
+| `idx_tplans_doctor` | `tplan_doctor_id` | Doctor's plans |
+| `idx_tplans_clinic` | `tplan_clinic_id` | Clinic-scoped plans |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `tplan_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `tplan_clinic_id` | Scoped clinic |
+| belongs_to | patients | `tplan_patient_id` | Patient this plan is for |
+| belongs_to | users | `tplan_doctor_id` | Doctor managing the plan |
+| has_many | treatment_plan_items | -- | Ordered items in this plan |
+| has_many | patient_photo_sets | -- | Before/after photos linked to this plan |
+
+**Design decisions:**
+- No financial fields (deferred). Total amount can be computed from items when needed.
+- `tplan_clinic_id` is required. A treatment plan belongs to the clinic where the patient is being treated.
+- `tplan_doctor_id` is optional — some plans may not have a specific doctor (e.g., general clinic plan).
+- `tplan_notes` encrypted with `PATIENT_PII_ENCRYPTION_KEY` — may contain clinical reasoning.
+- Plan auto-completes when all items reach `completed` status (application logic, not DB trigger).
+
+---
+
+### 42. treatment_plan_items
+
+**Purpose:** A single item within a treatment plan. Represents one procedure/visit. Linked to a treatment from the catalog and optionally to a booked appointment.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `tpitem_id` | UUID | Yes | `uuid()` | Primary key |
+| `tpitem_plan_id` | UUID | Yes | -- | FK to `treatment_plans` |
+| `tpitem_treatment_id` | UUID | No | `null` | FK to `treatments`. Null for custom one-off items |
+| `tpitem_appointment_id` | UUID | No | `null` | FK to `appointments`. Linked when appointment is booked |
+| `tpitem_name` | String | Yes | -- | Treatment name (denormalized — survives treatment deletion) |
+| `tpitem_tooth_number` | String | No | `null` | Dental-specific: tooth number (e.g., "14", "21-23") |
+| `tpitem_status` | TreatmentPlanItemStatus | Yes | `planned` | `planned`, `scheduled`, `in_progress`, `completed`, `cancelled` |
+| `tpitem_notes` | String | Yes | `""` | **Encrypted.** Notes about this specific item. AES-256-GCM via `PATIENT_PII_ENCRYPTION_KEY` |
+| `tpitem_sort_order` | Int | Yes | `0` | Display ordering within the plan |
+| `tpitem_completed_at` | DateTime | No | `null` | When this item was marked completed |
+| `tpitem_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `tpitem_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `tpitem_id` | PK lookup |
+| `idx_tpitems_plan_order` | `(tpitem_plan_id, tpitem_sort_order)` | Ordered item list within a plan |
+| `idx_tpitems_appointment` | `tpitem_appointment_id` | Find which plan item an appointment is for |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | treatment_plans | `tpitem_plan_id` | Parent plan (cascade delete) |
+| belongs_to | treatments | `tpitem_treatment_id` | Treatment from catalog (optional) |
+| belongs_to | appointments | `tpitem_appointment_id` | Linked appointment (optional) |
+
+**Design decisions:**
+- `tpitem_treatment_id` is nullable for custom/one-off items not in the catalog (e.g., "Special consultation").
+- `tpitem_name` is denormalized — if the treatment is renamed or deleted later, the plan item still shows what was planned.
+- `tpitem_notes` encrypted with `PATIENT_PII_ENCRYPTION_KEY` — may contain clinical details per procedure step.
+- `tpitem_tooth_number` is dental-specific. Aesthetic/dermatology clinics leave it null.
+- Status transitions: `planned` → `scheduled` (appointment linked) → `in_progress` → `completed`. Can be `cancelled` from any state.
+- Cascade delete from plan: deleting a plan removes all items.
+
+---
+
+### 43. doctor_profiles
+
+**Purpose:** Extended profile for users with the `doctor` role. Stores specialty, working hours, and appointment configuration. One-to-one with `users`.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `dprofile_id` | UUID | Yes | `uuid()` | Primary key |
+| `dprofile_user_id` | UUID | Yes (unique) | -- | FK to `users`. One-to-one |
+| `dprofile_specialty` | String | Yes | `""` | Specialty (e.g., "Ortodonti", "Implantoloji", "Estetik Cerrahi") |
+| `dprofile_title` | String | Yes | `""` | Professional title (e.g., "Dr.", "Dt.", "Prof. Dr.") |
+| `dprofile_bio` | String | Yes | `""` | Short biography / description |
+| `dprofile_working_hours` | Json | Yes | `"[]"` | Array of `{day, start, end}` objects defining availability |
+| `dprofile_appointment_duration` | Int | Yes | `30` | Default appointment slot duration in minutes |
+| `dprofile_color` | String | Yes | `""` | Calendar display color (hex, e.g., `#3B82F6`) |
+| `dprofile_is_accepting` | Boolean | Yes | `true` | Whether the doctor is accepting new patients/appointments |
+| `dprofile_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `dprofile_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `dprofile_id` | PK lookup |
+| Unique | `dprofile_user_id` | Enforce one-to-one with users |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | users | `dprofile_user_id` | Parent user (cascade delete) |
+
+**Design decisions:**
+- One-to-one with User. Created automatically when a user with `doctor` role is added.
+- `profile_working_hours` is JSONB because it is a variable-length array of per-day windows.
+- `profile_appointment_duration` overrides the clinic default when this doctor is selected for an appointment.
+- `profile_color` enables the frontend calendar to show each doctor's appointments in a distinct color.
+- `profile_is_accepting` allows temporarily stopping new bookings for a doctor without deactivating their user account.
+
+---
+
+### 44. patient_photo_sets
+
+**Purpose:** A group of related photos taken at a point in time for a patient. Used for before/after documentation of treatments. Each set contains multiple photos (different angles).
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `photoset_id` | UUID | Yes | `uuid()` | Primary key |
+| `photoset_patient_id` | UUID | Yes | -- | FK to `patients` |
+| `photoset_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `photoset_clinic_id` | UUID | Yes | -- | FK to `clinics` |
+| `photoset_treatment_plan_id` | UUID | No | `null` | FK to `treatment_plans`. Optional link to a treatment plan |
+| `photoset_type` | String | Yes | -- | `before`, `after_1week`, `after_1month`, `after_3months`, `progress`, `other` |
+| `photoset_label` | String | Yes | `""` | Free-form label (e.g., "Pre-op", "6 ay sonrasi") |
+| `photoset_taken_at` | DateTime | Yes | `now()` | When the photos were taken (not uploaded) |
+| `photoset_taken_by` | UUID | No | `null` | FK to `users`. Who took the photos |
+| `photoset_notes` | String | Yes | `""` | **Encrypted.** Notes about this photo set. AES-256-GCM via `PATIENT_PII_ENCRYPTION_KEY` |
+| `photoset_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `photoset_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `photoset_id` | PK lookup |
+| `idx_photosets_patient_date` | `(photoset_patient_id, photoset_taken_at DESC)` | Patient photo timeline |
+| `idx_photosets_plan` | `photoset_treatment_plan_id` | Photos for a treatment plan |
+| `idx_photosets_tenant_type` | `(photoset_tenant_id, photoset_type)` | Filter by type across tenant |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | patients | `photoset_patient_id` | Parent patient (cascade delete) |
+| belongs_to | tenants | `photoset_tenant_id` | Parent tenant |
+| belongs_to | clinics | `photoset_clinic_id` | Scoped clinic |
+| belongs_to | treatment_plans | `photoset_treatment_plan_id` | Linked treatment plan (optional) |
+| belongs_to | users | `photoset_taken_by` | Photographer |
+| has_many | patient_photos | -- | Individual photos in this set |
+
+**Design decisions:**
+- `photoset_taken_at` is separate from `created_at` — photos may be uploaded days after they were taken.
+- `photoset_type` is a string, not a Prisma enum — clinics may define custom photo set types.
+- `photoset_treatment_plan_id` enables grouping before/after photos by treatment plan for comparison views.
+- Cascade delete from patient: deleting a patient removes all photo sets and photos (+ MinIO cleanup).
+
+---
+
+### 45. patient_photos
+
+**Purpose:** Individual photos within a photo set. Each photo has an angle tag for structured comparison (front-to-front, left-to-left). Stored in MinIO.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `photo_id` | UUID | Yes | `uuid()` | Primary key |
+| `photo_set_id` | UUID | Yes | -- | FK to `patient_photo_sets` |
+| `photo_angle` | String | Yes | `""` | Photo angle: `front`, `left`, `right`, `top`, `bottom`, `smile`, `closeup`, `other` |
+| `photo_media_key` | String | Yes | -- | MinIO object key: `{tenantId}/patients/{patientId}/photos/{setId}/{photoId}.{ext}` |
+| `photo_thumbnail_key` | String | No | `null` | MinIO key for thumbnail (generated on upload) |
+| `photo_caption` | String | Yes | `""` | Optional caption |
+| `photo_sort_order` | Int | Yes | `0` | Display ordering within the set |
+| `photo_created_at` | DateTime | Yes | `now()` | Upload timestamp |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `photo_id` | PK lookup |
+| `idx_photos_set_order` | `(photo_set_id, photo_sort_order)` | Ordered photos within a set |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | patient_photo_sets | `photo_set_id` | Parent photo set (cascade delete) |
+
+**Design decisions:**
+- No `photo_updated_at`. Photos are immutable once uploaded. To replace, delete and re-upload.
+- `photo_angle` enables the frontend to align before/after photos by matching angles in comparison grids.
+- `photo_thumbnail_key` stores a pre-generated thumbnail (resized on upload) for fast list rendering without loading full images.
+- Cascade delete from photo set: deleting a set removes all photos (DB records). MinIO cleanup is handled by application code.
+- Served via signed URLs only. No public access.
+
+---
+
+### 46. examination_records
+
+**Purpose:** Per-visit clinical record. What the doctor found, diagnosed, performed, and prescribed during an appointment. One-to-one with `appointments`. Created when a doctor completes a visit.
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `exam_id` | UUID | Yes | `uuid()` | Primary key |
+| `exam_appointment_id` | UUID | Yes (unique) | -- | FK to `appointments`. One-to-one |
+| `exam_patient_id` | UUID | Yes | -- | FK to `patients`. Denormalized for direct patient queries |
+| `exam_doctor_id` | UUID | Yes | -- | FK to `users` (doctor role). Who performed the examination |
+| `exam_clinic_id` | UUID | Yes | -- | FK to `clinics` |
+| `exam_tenant_id` | UUID | Yes | -- | FK to `tenants` |
+| `exam_findings` | String | Yes | `""` | **Encrypted.** What the doctor observed. AES-256-GCM via `PATIENT_PII_ENCRYPTION_KEY` |
+| `exam_diagnosis` | String | Yes | `""` | **Encrypted.** Diagnosis. Same key |
+| `exam_procedure_notes` | String | Yes | `""` | **Encrypted.** What was done during the visit. Same key |
+| `exam_prescription` | String | Yes | `""` | **Encrypted.** Medications prescribed. Same key |
+| `exam_instructions` | String | Yes | `""` | **Encrypted.** Follow-up instructions for the patient. Same key |
+| `exam_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `exam_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `exam_id` | PK lookup |
+| Unique | `exam_appointment_id` | Enforce one-to-one with appointments |
+| `idx_exam_patient_date` | `(exam_patient_id, exam_created_at DESC)` | Patient examination history |
+| `idx_exam_doctor_date` | `(exam_doctor_id, exam_created_at DESC)` | Doctor's examination history |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | appointments | `exam_appointment_id` | Which appointment this exam is for (cascade delete) |
+| belongs_to | patients | `exam_patient_id` | Patient examined |
+| belongs_to | users (doctor) | `exam_doctor_id` | Doctor who performed the exam |
+| belongs_to | clinics | `exam_clinic_id` | Which clinic |
+| belongs_to | tenants | `exam_tenant_id` | Parent tenant (cascade delete) |
+
+**Design decisions:**
+- **All clinical text fields are encrypted** with `PATIENT_PII_ENCRYPTION_KEY`. Findings, diagnosis, procedure notes, prescription, and instructions are sensitive health data.
+- One-to-one with appointments. Not every appointment has an exam record (e.g., no-shows, cancelled). The record is created when the doctor fills in the clinical form after the visit.
+- `exam_patient_id` is denormalized (could be resolved via appointment → patient). Direct FK enables efficient patient timeline queries without joining through appointments.
+- This is the **per-visit record**. The static background health info (allergies, conditions) stays in `patient_medical_histories` (#37).