elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/19-PATIENTS.md

@@ -0,0 +1,1034 @@
+# Patients
+
+> Central entity for the clinic management pivot. Everything links back to Patient:
+> appointments, conversations, calls, treatment plans, photos, documents, notes.
+> Replaces `WhatsAppContactProfile` as the core identity.
+> Last updated: 2026-03-29
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Patient Model](#2-patient-model)
+3. [Medical History (Anamnesis)](#3-medical-history-anamnesis)
+4. [Patient Documents](#4-patient-documents)
+5. [Patient Notes](#5-patient-notes)
+6. [Patient Timeline](#6-patient-timeline)
+7. [Auto-Creation from AI Contact](#7-auto-creation-from-ai-contact)
+8. [API Endpoints](#8-api-endpoints)
+9. [Permissions](#9-permissions)
+10. [Patient Merge (Duplicate Resolution)](#10-patient-merge-duplicate-resolution)
+11. [WhatsAppContactProfile Migration](#11-whatsappcontactprofile-migration)
+12. [NestJS Module Structure](#12-nestjs-module-structure)
+13. [Feature Flag](#13-feature-flag)
+14. [Affected Existing Models](#14-affected-existing-models)
+
+---
+
+## 1. Overview
+
+The product pivot from pure AI receptionist to full clinic management tool makes Patient the central entity in the data model. Every piece of data ultimately connects back to a patient:
+
+```
+Patient
+  |
+  +-- Appointments         (booked, cancelled, completed, no_show)
+  +-- WhatsApp Chats       (conversations with AI and staff)
+  +-- Calls                (inbound, outbound, with summaries)
+  +-- Operator Requests    (photo reviews forwarded to doctor)
+  +-- Treatment Plans      (planned and completed procedures)
+  +-- Photo Sets           (before/after clinical photos)
+  +-- Documents            (consent forms, lab results, x-rays)
+  +-- Notes                (staff observations, pinned items)
+  +-- Tasks                (follow-ups, reminders)
+  +-- Medical History      (allergies, conditions, medications)
+```
+
+**Key principles:**
+
+- **Auto-created on first AI contact.** When a patient sends a WhatsApp message, makes a voice call, or sends an Instagram DM, a Patient record is created automatically with whatever information is available (phone number, display name from the messaging platform).
+- **Staff enriches from dashboard.** Demographics, medical history, documents, and tags are filled in by clinic staff over time.
+- **Replaces WhatsAppContactProfile.** The existing `whatsapp_contact_profiles` table is superseded. All its data migrates into `patients` and related tables. See [Section 11](#11-whatsappcontactprofile-migration).
+- **Multi-channel identity.** A patient is identified primarily by phone number (E.164) within a tenant. The same person contacting via WhatsApp and voice call is the same Patient record.
+
+---
+
+## 2. Patient Model
+
+### Prisma Schema
+
+```prisma
+model Patient {
+  patient_id                 String    @id @default(uuid())
+  patient_tenant_id          String
+  patient_clinic_id          String?   // Primary clinic
+  patient_phone              String    // E.164, primary identifier
+  patient_email              String?
+  patient_first_name         String
+  patient_last_name          String
+  patient_display_name       String    @default("")  // Auto-built or manual
+  patient_date_of_birth      DateTime?
+  patient_gender             String?   // male | female | other
+  patient_id_number          String?   // TC Kimlik No
+  patient_blood_type         String?
+  patient_preferred_language String    @default("tr")
+  patient_source             String?   // instagram_ad | google | referral | walk_in | whatsapp | voice_call | campaign
+  patient_source_detail      String?   // Which campaign, referrer name, ad ID
+  patient_tags               String[]  @default([])
+  patient_ai_summary         String    @default("")  // AI-generated from conversations
+  patient_is_active          Boolean   @default(true)
+  patient_first_contact_at   DateTime  @default(now())
+  patient_last_contact_at    DateTime  @default(now())
+  patient_total_sessions     Int       @default(0)
+  patient_total_appointments Int       @default(0)
+  patient_created_at         DateTime  @default(now())
+  patient_updated_at         DateTime  @updatedAt
+
+  tenant              Tenant                @relation(fields: [patient_tenant_id], references: [tenant_id], onDelete: Cascade)
+  clinic              Clinic?               @relation(fields: [patient_clinic_id], references: [clinic_id])
+  medicalHistory      PatientMedicalHistory?
+  treatmentPlans      TreatmentPlan[]
+  appointments        Appointment[]
+  photoSets           PatientPhotoSet[]
+  documents           PatientDocument[]
+  notes               PatientNote[]
+  chats               WhatsAppChat[]
+  operatorRequests    OperatorRequest[]
+  tasks               Task[]
+
+  @@unique([patient_tenant_id, patient_phone])
+  @@index([patient_tenant_id, patient_last_contact_at(sort: Desc)])
+  @@index([patient_clinic_id])
+  @@index([patient_tenant_id, patient_last_name, patient_first_name])
+  @@map("patients")
+}
+```
+
+### Column Descriptions
+
+| 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 for this patient. Null if not yet assigned (auto-created patients start unassigned, routed clinic is set on creation if known) |
+| `patient_phone` | String | Yes | -- | Phone number in E.164 format (e.g., `+905551234567`). Primary identifier for cross-channel matching |
+| `patient_email` | String | No | `null` | Email address. Optional, entered by staff |
+| `patient_first_name` | String | Yes | -- | First name. May be extracted from display name on auto-creation |
+| `patient_last_name` | String | Yes | -- | Last name. May be `"Bilinmiyor"` (Unknown) on auto-creation |
+| `patient_display_name` | String | Yes | `""` | Display name shown in UI. Auto-built from first + last name, or manually overridden. On auto-creation, populated from WhatsApp push name or contact info |
+| `patient_date_of_birth` | DateTime | No | `null` | Date of birth. Entered by staff or collected by AI |
+| `patient_gender` | String | No | `null` | Gender: `male`, `female`, or `other`. String rather than enum to avoid migration for future values |
+| `patient_id_number` | String | No | `null` | Turkish national ID number (TC Kimlik No). 11 digits. Used for government reporting |
+| `patient_blood_type` | String | No | `null` | Blood type (e.g., `A+`, `B-`, `0+`, `AB-`). Relevant for surgical clinics |
+| `patient_preferred_language` | String | Yes | `"tr"` | ISO 639-1 language code. Determines AI agent language selection |
+| `patient_source` | String | No | `null` | How the patient first reached the clinic. Values: `instagram_ad`, `google`, `referral`, `walk_in`, `whatsapp`, `voice_call`, `campaign`. String rather than enum because clinics will add custom sources |
+| `patient_source_detail` | String | No | `null` | Free text detail about the source. Examples: campaign name, referrer's name, specific ad ID, Google Ads keyword |
+| `patient_tags` | String[] | Yes | `[]` | Tags for categorization (e.g., `["dental", "vip", "returning"]`). Array rather than junction table -- tags are simple text labels, not referential entities |
+| `patient_ai_summary` | String | Yes | `""` | AI-generated summary aggregated from all conversations. Regenerated asynchronously (BullMQ job) after each session resolves |
+| `patient_is_active` | Boolean | Yes | `true` | Soft-delete flag. `false` = patient is archived/deleted. Filtered out of default queries |
+| `patient_first_contact_at` | DateTime | Yes | `now()` | Timestamp of the patient's first interaction with the clinic (any channel) |
+| `patient_last_contact_at` | DateTime | Yes | `now()` | Timestamp of the patient's most recent interaction. Updated on every message, call, or appointment |
+| `patient_total_sessions` | Int | Yes | `0` | Denormalized counter of WhatsApp sessions. Incremented on session create. Avoids COUNT queries on the patient list page |
+| `patient_total_appointments` | Int | Yes | `0` | Denormalized counter of appointments (all statuses). Incremented on appointment create |
+| `patient_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `patient_updated_at` | DateTime | Yes | auto | Automatically updated on every write via Prisma `@updatedAt` |
+
+### Indexes
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `patient_id` | PK lookup |
+| Unique | `(patient_tenant_id, patient_phone)` | One patient per phone per tenant. The core deduplication constraint |
+| `idx_patients_tenant_lastcontact` | `(patient_tenant_id, patient_last_contact_at DESC)` | Patient list sorted by most recent contact (default sort) |
+| `idx_patients_clinic` | `(patient_clinic_id)` | Filter patients by primary clinic |
+| `idx_patients_tenant_name` | `(patient_tenant_id, patient_last_name, patient_first_name)` | Alphabetical patient list, 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 (nullable) |
+| has_one | patient_medical_histories | -- | Medical history / anamnesis |
+| has_many | treatment_plans | -- | Treatment plans |
+| has_many | appointments | -- | All appointments (via `appt_patient_id`) |
+| has_many | patient_photo_sets | -- | Clinical photo sets |
+| has_many | patient_documents | -- | Uploaded documents |
+| has_many | patient_notes | -- | Staff notes |
+| has_many | whatsapp_chats | -- | WhatsApp conversations (via `chat_patient_id`) |
+| has_many | operator_requests | -- | Operator workflow requests (via session -> chat -> patient) |
+| has_many | tasks | -- | Follow-up tasks |
+
+### Design Decisions
+
+- **`patient_phone` as primary identifier, not `patient_id_number`.** TC Kimlik is optional -- many patients never provide it. Phone number is always available because it is the contact method. The `(tenant_id, phone)` unique constraint is the deduplication key.
+- **`patient_clinic_id` is nullable.** Auto-created patients may not have a known primary clinic if the routing context is ambiguous. Staff assigns the clinic later. For single-clinic tenants, it is set to the default clinic on creation.
+- **`patient_source` is String, not Prisma enum.** Clinics will want custom acquisition sources (specific campaigns, partner names). Adding a value should not require a database migration.
+- **`patient_gender` is String, not Prisma enum.** Same rationale. The common values are `male`, `female`, `other`, but the field is not constrained at the DB level.
+- **`patient_tags` is `String[]`, not a junction table.** Tags are simple text labels used for filtering and display. They are not entities with their own properties. Array containment queries (`@>`) are sufficient.
+- **Denormalized counters (`patient_total_sessions`, `patient_total_appointments`).** The patient list page shows these counts. Running `COUNT(*)` with JOINs for every row in a paginated list is expensive. Counters are incremented atomically on session/appointment creation.
+- **`patient_display_name` is separate from `first_name` + `last_name`.** Auto-created patients often have only a WhatsApp push name (e.g., "Mehmet A.") that does not split cleanly into first and last. The display name stores whatever the system has. Staff can override it later.
+
+---
+
+## 3. Medical History (Anamnesis)
+
+### Prisma Schema
+
+```prisma
+model PatientMedicalHistory {
+  history_id                  String    @id @default(uuid())
+  history_patient_id          String    @unique
+  history_allergies           String[]  @default([])
+  history_chronic_conditions  String[]  @default([])
+  history_current_medications String[]  @default([])
+  history_past_surgeries      String    @default("")
+  history_pregnancy_status    String?   // not_applicable | not_pregnant | pregnant | unknown
+  history_smoking             Boolean?
+  history_alcohol             Boolean?
+  history_notes               String    @default("")
+  history_anamnesis_completed Boolean   @default(false)
+  history_anamnesis_date      DateTime?
+  history_created_at          DateTime  @default(now())
+  history_updated_at          DateTime  @updatedAt
+
+  patient Patient @relation(fields: [history_patient_id], references: [patient_id], onDelete: Cascade)
+
+  @@map("patient_medical_histories")
+}
+```
+
+### Column Descriptions
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `history_id` | UUID | Yes | `uuid()` | Primary key |
+| `history_patient_id` | UUID | Yes | -- | FK to `patients`. One-to-one (unique constraint) |
+| `history_allergies` | String[] | Yes | `[]` | Known allergies (e.g., `["penisilin", "lateks"]`). Free text array |
+| `history_chronic_conditions` | String[] | Yes | `[]` | Chronic conditions (e.g., `["diyabet", "hipertansiyon"]`). Free text array |
+| `history_current_medications` | String[] | Yes | `[]` | Medications currently being taken (e.g., `["metformin 500mg", "aspirin 100mg"]`) |
+| `history_past_surgeries` | String | Yes | `""` | Free text description of past surgical procedures |
+| `history_pregnancy_status` | String | No | `null` | Pregnancy status: `not_applicable`, `not_pregnant`, `pregnant`, `unknown`. Relevant for dental/cosmetic procedures (anesthesia, X-ray contraindications) |
+| `history_smoking` | Boolean | No | `null` | Whether the patient smokes. Affects healing timelines and treatment plans. `null` = not asked |
+| `history_alcohol` | Boolean | No | `null` | Whether the patient consumes alcohol regularly. `null` = not asked |
+| `history_notes` | String | Yes | `""` | Free text notes from the doctor about the patient's medical background |
+| `history_anamnesis_completed` | Boolean | Yes | `false` | Whether a doctor has completed the anamnesis form. Controls UI state (show "incomplete" badge) |
+| `history_anamnesis_date` | DateTime | No | `null` | When the anamnesis was completed. Set when `history_anamnesis_completed` transitions to `true` |
+| `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` | 1:1 relationship enforcement |
+
+### Relations
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | patients | `history_patient_id` | Parent patient (cascade delete) |
+
+### Design Decisions
+
+- **Separate table, not JSONB.** Medical history is a distinct clinical concern, queried independently from patient demographics. Turkish healthcare regulations (KVKK, Saglik Bakanligi) may require specific field-level audit trails. A dedicated table makes this straightforward.
+- **Created empty on patient creation.** The `PatientMedicalHistory` record is always created alongside the Patient (even for auto-created patients). This avoids null-checking in every medical history read -- the row always exists, just with defaults.
+- **Arrays for allergies, conditions, medications.** These are free-text lists, not coded medical terminologies (ICD-10, ATC). Turkish clinics primarily use free text. If coded terminology is needed later, it can be added as a parallel field without breaking existing data.
+- **`history_pregnancy_status` is String.** The values are a small fixed set but stored as String to avoid an enum migration for edge cases (e.g., `postpartum`).
+
+---
+
+## 4. Patient Documents
+
+### Prisma Schema
+
+```prisma
+model PatientDocument {
+  doc_id           String   @id @default(uuid())
+  doc_patient_id   String
+  doc_tenant_id    String
+  doc_type         String   // consent_form | lab_result | x_ray | prescription | referral | other
+  doc_name         String
+  doc_media_key    String   // MinIO key: {tenantId}/patients/{patientId}/documents/{docId}.{ext}
+  doc_content_type String   // MIME type
+  doc_size_bytes   Int      @default(0)
+  doc_uploaded_by  String?  // FK to users
+  doc_notes        String   @default("")
+  doc_created_at   DateTime @default(now())
+
+  patient    Patient @relation(fields: [doc_patient_id], references: [patient_id], onDelete: Cascade)
+  tenant     Tenant  @relation(fields: [doc_tenant_id], references: [tenant_id], onDelete: Cascade)
+  uploadedBy User?   @relation(fields: [doc_uploaded_by], references: [user_id])
+
+  @@index([doc_patient_id, doc_created_at(sort: Desc)])
+  @@index([doc_tenant_id, doc_type])
+  @@map("patient_documents")
+}
+```
+
+### Column Descriptions
+
+| 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`. Denormalized for tenant-level queries (e.g., "all X-rays for this tenant") |
+| `doc_type` | String | Yes | -- | Document type: `consent_form`, `lab_result`, `x_ray`, `prescription`, `referral`, `other`. String rather than Prisma enum because clinics will want custom types |
+| `doc_name` | String | Yes | -- | Human-readable document name (e.g., "Panoramik Rontgen 2026-03-15") |
+| `doc_media_key` | String | Yes | -- | MinIO object key. Format: `{tenantId}/patients/{patientId}/documents/{docId}.{ext}`. Never exposed to frontend -- served via signed URLs |
+| `doc_content_type` | String | Yes | -- | MIME type (e.g., `image/jpeg`, `application/pdf`, `image/png`) |
+| `doc_size_bytes` | Int | Yes | `0` | File size in bytes. Used for storage quota calculations and display |
+| `doc_uploaded_by` | UUID | No | `null` | FK to `users`. The staff member who uploaded the document. Null for system-generated documents |
+| `doc_notes` | String | Yes | `""` | Free text notes about the document (e.g., "Left molar area") |
+| `doc_created_at` | DateTime | Yes | `now()` | Upload timestamp. No `updated_at` -- documents are immutable once uploaded (delete and re-upload to replace) |
+
+### Indexes
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `doc_id` | PK lookup |
+| `idx_docs_patient_created` | `(doc_patient_id, doc_created_at DESC)` | Patient document list sorted by recency |
+| `idx_docs_tenant_type` | `(doc_tenant_id, doc_type)` | Filter all documents of a type for a 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 (cascade delete) |
+| belongs_to | users | `doc_uploaded_by` | Staff member who uploaded (nullable) |
+
+### Design Decisions
+
+- **Stored in MinIO, not in the database.** Following the architecture rule from [18-FILE-STORAGE.md](18-FILE-STORAGE.md): no base64 in database. The database stores only the MinIO object key. All access is through signed URLs with 1-hour TTL.
+- **MinIO path format:** `{tenantId}/patients/{patientId}/documents/{docId}.{ext}`. This extends the bucket structure defined in the file storage doc.
+- **`doc_type` is String, not Prisma enum.** Clinics across different specialties need different document types. A dermatology clinic might add `dermoscopy_image`, an orthodontist might add `ceph_analysis`. Adding types should not require schema migrations.
+- **No `updated_at`.** Documents are immutable after upload. To "update" a document, delete the old one and upload a new version. This keeps the MinIO lifecycle simple and avoids partial-update edge cases.
+- **`doc_uploaded_by` nullable.** System-generated documents (e.g., auto-saved WhatsApp media promoted to documents) have no human uploader.
+
+### Upload Flow
+
+```
+Staff clicks "Upload Document" on patient detail page
+  |
+  v
+Frontend: POST /patients/:id/documents (multipart/form-data)
+  |  Fields: file, doc_type, doc_name, doc_notes
+  v
+Backend (DocumentsService):
+  1. Validate file type and size (max 20MB)
+  2. Generate doc_id (UUID)
+  3. Construct MinIO key: {tenantId}/patients/{patientId}/documents/{docId}.{ext}
+  4. Upload to MinIO: minioService.putObject(key, buffer, contentType)
+  5. Create PatientDocument row in DB
+  6. Return document record with signed URL for immediate display
+```
+
+### Serving Documents
+
+```
+Frontend requests document list: GET /patients/:id/documents
+  |
+  v
+Backend:
+  1. Query PatientDocument rows for patient
+  2. For each document, generate signed URL: minioService.presignedGetObject(doc_media_key, 3600)
+  3. Return documents with signed URLs
+  |
+  v
+Frontend displays documents with time-limited URLs (1-hour TTL)
+```
+
+---
+
+## 5. Patient Notes
+
+### Prisma Schema
+
+```prisma
+model PatientNote {
+  note_id         String   @id @default(uuid())
+  note_patient_id String
+  note_tenant_id  String
+  note_author_id  String
+  note_text       String
+  note_is_pinned  Boolean  @default(false)
+  note_created_at DateTime @default(now())
+  note_updated_at DateTime @updatedAt
+
+  patient Patient @relation(fields: [note_patient_id], references: [patient_id], onDelete: Cascade)
+  tenant  Tenant  @relation(fields: [note_tenant_id], references: [tenant_id], onDelete: Cascade)
+  author  User    @relation(fields: [note_author_id], references: [user_id])
+
+  @@index([note_patient_id, note_created_at(sort: Desc)])
+  @@map("patient_notes")
+}
+```
+
+### Column Descriptions
+
+| 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`. Denormalized for tenant-level queries |
+| `note_author_id` | UUID | Yes | -- | FK to `users`. The staff member who wrote the note. Required -- every note has an author |
+| `note_text` | String | Yes | -- | Note content. Plain text, no rich formatting |
+| `note_is_pinned` | Boolean | Yes | `false` | Pinned notes appear at the top of the patient detail notes section. Useful for critical information (e.g., "patient is allergic to anesthesia") |
+| `note_created_at` | DateTime | Yes | `now()` | When the note was written |
+| `note_updated_at` | DateTime | Yes | auto | Automatically updated on edit |
+
+### Indexes
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `note_id` | PK lookup |
+| `idx_notes_patient_created` | `(note_patient_id, note_created_at DESC)` | Note list sorted by recency |
+
+### Relations
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | patients | `note_patient_id` | Parent patient (cascade delete) |
+| belongs_to | tenants | `note_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | users | `note_author_id` | Note author |
+
+### Design Decisions
+
+- **Author is required.** Every note must have an author. The author's name is resolved via JOIN at query time (not denormalized) because note lists are small per patient and the JOIN is cheap.
+- **No separate "note type" field.** Notes are simple text entries. If structured clinical notes are needed later (e.g., SOAP format), that would be a different model (`ClinicalNote`), not an overloading of this one.
+- **Pinned notes.** A simple boolean flag. The patient detail UI orders notes as: pinned notes first (by created_at DESC), then unpinned notes (by created_at DESC). No limit on pinned notes -- trust the staff.
+
+---
+
+## 6. Patient Timeline
+
+The timeline is **not a separate table**. It is a computed view that merges multiple data sources into a single chronological feed.
+
+### 6.1 Timeline Sources
+
+```
+Patient Timeline = UNION ALL of:
+  - Appointments       (booked, cancelled, completed, no_show)
+  - WhatsApp sessions  (created, resolved, messages)
+  - Calls              (inbound, outbound, with summaries)
+  - Operator requests  (forwarded, responded, expired)
+  - Treatment plans    (created, item completed)
+  - Documents uploaded
+  - Notes added
+  - Photo sets added
+  - Tasks              (created, completed)
+
+Sorted by timestamp DESC, paginated.
+```
+
+### 6.2 Timeline Entry Shape
+
+Each timeline entry is normalized to a common shape before returning to the frontend:
+
+```typescript
+interface TimelineEntry {
+  id: string;             // Source record ID
+  type: TimelineType;     // 'appointment' | 'session' | 'call' | 'operator_request' | ...
+  timestamp: Date;        // Event timestamp (used for sorting)
+  title: string;          // Human-readable title (e.g., "Randevu - 15 Mart 10:00")
+  description: string;    // Summary or snippet
+  metadata: Record<string, any>;  // Type-specific data for the frontend to render
+  actor?: {               // Who performed the action (null for system events)
+    id: string;
+    name: string;
+    role: string;
+  };
+}
+
+type TimelineType =
+  | 'appointment'
+  | 'session'
+  | 'call'
+  | 'operator_request'
+  | 'treatment_plan'
+  | 'document'
+  | 'note'
+  | 'photo_set'
+  | 'task';
+```
+
+### 6.3 Implementation
+
+The timeline is assembled by `TimelineService`, which runs parallel queries against multiple tables and merges the results in memory:
+
+```
+GET /patients/:id/timeline?page=1&limit=20&types=appointment,call,session
+  |
+  v
+TimelineService.getTimeline(patientId, { page, limit, types })
+  |
+  v
+  1. Determine which sources to query (from "types" filter, default = all)
+  2. Run queries in parallel (Promise.all):
+     - appointmentsRepo.findByPatient(patientId, { take: limit + 1, orderBy: start_time DESC })
+     - whatsappSessionsRepo.findByPatient(patientId, { take: limit + 1, orderBy: created_at DESC })
+     - callsRepo.findByPatientPhone(patientPhone, tenantId, { take: limit + 1, orderBy: created_at DESC })
+     - operatorRequestsRepo.findByPatient(patientId, { take: limit + 1, orderBy: created_at DESC })
+     - documentsRepo.findByPatient(patientId, { take: limit + 1, orderBy: created_at DESC })
+     - notesRepo.findByPatient(patientId, { take: limit + 1, orderBy: created_at DESC })
+     - ... (other sources)
+  3. Transform each result set into TimelineEntry[]
+  4. Merge all entries into a single array
+  5. Sort by timestamp DESC
+  6. Apply cursor-based or offset pagination (take first "limit" entries)
+  7. Return { entries, hasMore, nextCursor }
+```
+
+**Why not a materialized view or dedicated table:**
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| Materialized view | Fast reads | Stale data, complex refresh triggers, PostgreSQL-specific |
+| Dedicated timeline_events table | Simple queries | Write amplification (every action writes twice), schema coupling |
+| **Parallel queries + in-memory merge** | Always fresh, no write overhead, source-independent | Slightly more complex service code, N+1 risk (mitigated by per-source LIMIT) |
+
+The parallel query approach is chosen because:
+- Timeline is read infrequently (only on patient detail page).
+- Each source query is indexed and fast (all have `(patient_id, timestamp DESC)` indexes).
+- Over-fetching per source (limit + 1) and merging gives correct pagination without full table scans.
+
+### 6.4 Endpoint
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/patients/:id/timeline` | `patients:read` | Unified activity timeline |
+
+**Query parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | Int | `1` | Page number (offset-based) |
+| `limit` | Int | `20` | Items per page (max 50) |
+| `types` | String | all | Comma-separated filter: `appointment,call,session,operator_request,treatment_plan,document,note,photo_set,task` |
+
+---
+
+## 7. Auto-Creation from AI Contact
+
+When the AI system receives a message or call from an unknown phone number, a Patient record is created automatically. This replaces the current `WhatsAppContactProfile` upsert logic.
+
+### 7.1 Sequence Diagram
+
+```
+Incoming WhatsApp message from unknown phone
+       |
+       v
+  Webhook handler extracts sender phone (E.164)
+       |
+       v
+  PatientService.findOrCreate(tenantId, phone, metadata)
+       |
+       v
+  SELECT FROM patients WHERE patient_tenant_id = :tenantId AND patient_phone = :phone
+       |
+       +-- Found --> return existing Patient
+       |
+       +-- Not found
+             |
+             v
+           1. Determine clinic from routing context (PhoneNumber -> Clinic)
+           2. Extract display name from WhatsApp push name or voice call caller ID
+           3. Attempt to split display name into first + last name
+              (heuristic: last word = last name, rest = first name)
+           4. INSERT Patient:
+                patient_phone = phone
+                patient_first_name = extracted or "Bilinmiyor"
+                patient_last_name = extracted or "Bilinmiyor"
+                patient_display_name = raw push name or phone number
+                patient_clinic_id = routed clinic ID (nullable)
+                patient_source = channel ('whatsapp' | 'voice_call' | 'instagram')
+                patient_first_contact_at = now()
+                patient_last_contact_at = now()
+           5. INSERT PatientMedicalHistory (empty, linked to new patient)
+           6. Link WhatsAppChat.chat_patient_id = new patient ID
+           7. Return new Patient
+```
+
+### 7.2 Channel-Specific Behavior
+
+| Channel | Display Name Source | Source Value | Additional Data |
+|---------|-------------------|--------------|-----------------|
+| WhatsApp (Baileys) | Push name from `message.pushName` | `whatsapp` | -- |
+| WhatsApp (Meta Business) | Profile name from contact info | `whatsapp` | -- |
+| Voice Call (Inbound) | Caller ID (if available) | `voice_call` | -- |
+| Voice Call (Outbound) | From campaign/validation entry data | `campaign` | `patient_source_detail` = campaign name |
+| Instagram DM | Instagram username | `instagram_ad` | `patient_source_detail` = IG handle |
+
+### 7.3 Deduplication
+
+The `(patient_tenant_id, patient_phone)` unique constraint prevents duplicates. If two concurrent requests try to create the same patient, the second INSERT fails with a unique constraint violation. The service catches this, re-reads the existing record, and returns it.
+
+```typescript
+async findOrCreate(tenantId: string, phone: string, metadata: PatientAutoCreateMetadata): Promise<Patient> {
+  // Try to find existing
+  const existing = await this.prisma.patient.findUnique({
+    where: { patient_tenant_id_patient_phone: { patient_tenant_id: tenantId, patient_phone: phone } },
+  });
+  if (existing) {
+    // Update last_contact_at
+    await this.prisma.patient.update({
+      where: { patient_id: existing.patient_id },
+      data: { patient_last_contact_at: new Date() },
+    });
+    return existing;
+  }
+
+  // Create new -- handle race condition
+  try {
+    const patient = await this.prisma.$transaction(async (tx) => {
+      const p = await tx.patient.create({ data: { ... } });
+      await tx.patientMedicalHistory.create({ data: { history_patient_id: p.patient_id } });
+      return p;
+    });
+    return patient;
+  } catch (err) {
+    if (err.code === 'P2002') {  // Prisma unique constraint violation
+      return this.prisma.patient.findUniqueOrThrow({
+        where: { patient_tenant_id_patient_phone: { patient_tenant_id: tenantId, patient_phone: phone } },
+      });
+    }
+    throw err;
+  }
+}
+```
+
+---
+
+## 8. API Endpoints
+
+### Patient CRUD
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/patients` | `patients:read` | List patients (paginated, searchable by name/phone, filterable by clinic/tag/source) |
+| POST | `/patients` | `patients:create` | Create patient manually (walk-in, phone registration) |
+| GET | `/patients/:id` | `patients:read` | Patient detail with medical history and stats |
+| PUT | `/patients/:id` | `patients:update` | Update demographics, tags |
+| DELETE | `/patients/:id` | `patients:delete` | Soft-delete (set `patient_is_active = false`) |
+
+### Search
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/patients/search` | `patients:read` | Quick search by name or phone (autocomplete). Returns max 10 results. Used by search bars across the dashboard |
+
+**Search query logic:** `WHERE (patient_first_name ILIKE :q% OR patient_last_name ILIKE :q% OR patient_phone LIKE :q%) AND patient_tenant_id = :tenantId AND patient_is_active = true`. Uses the `idx_patients_tenant_name` index for name searches and the unique index for phone searches.
+
+### Timeline
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/patients/:id/timeline` | `patients:read` | Unified activity timeline (see [Section 6](#6-patient-timeline)) |
+
+### Medical History
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/patients/:id/medical-history` | `patients:read` | Medical history / anamnesis |
+| PUT | `/patients/:id/medical-history` | `patients:update` | Update medical history. Sets `history_anamnesis_completed = true` and `history_anamnesis_date = now()` on first complete submission |
+
+### Documents
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/patients/:id/documents` | `patients:read` | List documents (with signed URLs) |
+| POST | `/patients/:id/documents` | `patients:update` | Upload document (multipart/form-data -> MinIO) |
+| DELETE | `/patients/:id/documents/:docId` | `patients:update` | Delete document (removes from MinIO and DB) |
+
+### Notes
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/patients/:id/notes` | `patients:read` | List notes (pinned first, then by created_at DESC) |
+| POST | `/patients/:id/notes` | `patients:update` | Add note (author = current user) |
+| PUT | `/patients/:id/notes/:noteId` | `patients:update` | Edit note text or pin/unpin |
+| DELETE | `/patients/:id/notes/:noteId` | `patients:update` | Delete note |
+
+### Merge
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| POST | `/patients/merge` | `patients:update` | Merge duplicate patients (see [Section 10](#10-patient-merge-duplicate-resolution)) |
+
+### List Endpoint Query Parameters
+
+`GET /patients` supports the following query parameters:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | Int | `1` | Page number |
+| `limit` | Int | `20` | Items per page (max 100) |
+| `search` | String | -- | Search by name or phone (ILIKE) |
+| `clinic_id` | UUID | -- | Filter by primary clinic |
+| `source` | String | -- | Filter by acquisition source |
+| `tag` | String | -- | Filter by tag (array containment) |
+| `is_active` | Boolean | `true` | Include archived patients |
+| `sort` | String | `last_contact_at` | Sort field: `last_contact_at`, `first_name`, `created_at`, `total_appointments` |
+| `order` | String | `desc` | Sort order: `asc`, `desc` |
+
+---
+
+## 9. Permissions
+
+### New Permission Keys
+
+| Permission | Description |
+|------------|-------------|
+| `patients:read` | View patient list and detail pages |
+| `patients:create` | Create new patients manually (walk-in, phone registration) |
+| `patients:update` | Edit patient demographics, medical history, documents, notes |
+| `patients:delete` | Soft-delete (archive) patients |
+| `patients:export` | Export patient data (CSV download, KVKK data packages) |
+
+### Role Mapping
+
+| Role | `patients:read` | `patients:create` | `patients:update` | `patients:delete` | `patients:export` |
+|------|-----------------|--------------------|--------------------|--------------------|--------------------|
+| owner | Yes | Yes | Yes | Yes | Yes |
+| admin | Yes | Yes | Yes | No | Yes |
+| doctor | Yes | No | Yes (medical history, notes only) | No | No |
+| receptionist | Yes | Yes | Yes (demographics only, not medical history) | No | No |
+
+### Role-Specific Update Restrictions
+
+The `patients:update` permission is further scoped by role at the service level:
+
+- **doctor:** Can update `PatientMedicalHistory` and `PatientNote`. Cannot update patient demographics (`patient_first_name`, `patient_last_name`, `patient_tags`, etc.).
+- **receptionist:** Can update patient demographics and add notes. Cannot update `PatientMedicalHistory`.
+- **admin/owner:** Can update everything.
+
+This is enforced in `PatientsService.update()` and `MedicalHistoryService.update()` by checking the user's role before applying changes. Not a separate permission key -- role-based field filtering.
+
+---
+
+## 10. Patient Merge (Duplicate Resolution)
+
+Duplicates arise when the same person contacts via different channels or phone numbers. For example: a patient texts from their personal WhatsApp, then calls from their work phone. Two Patient records exist for the same person.
+
+### 10.1 Merge Endpoint
+
+```
+POST /patients/merge
+{
+  "primary_patient_id": "uuid-1",   // Keeps its ID, receives all data
+  "secondary_patient_id": "uuid-2"  // Merges into primary, gets soft-deleted
+}
+```
+
+Permission: `patients:update`
+
+### 10.2 Merge Algorithm
+
+```
+POST /patients/merge { primary_patient_id, secondary_patient_id }
+  |
+  v
+1. Validate both patients belong to the same tenant
+2. Validate neither patient is already soft-deleted
+3. Begin transaction:
+  |
+  +-- 4. Re-link all child records from secondary to primary:
+  |       UPDATE appointments SET appt_patient_id = :primary WHERE appt_patient_id = :secondary
+  |       UPDATE whatsapp_chats SET chat_patient_id = :primary WHERE chat_patient_id = :secondary
+  |       UPDATE patient_documents SET doc_patient_id = :primary WHERE doc_patient_id = :secondary
+  |       UPDATE patient_notes SET note_patient_id = :primary WHERE note_patient_id = :secondary
+  |       UPDATE patient_photo_sets SET ... WHERE ... = :secondary
+  |       UPDATE tasks SET ... WHERE ... = :secondary
+  |       (treatment_plans, operator_requests follow same pattern)
+  |
+  +-- 5. Merge medical history:
+  |       Primary wins on scalar conflicts (smoking, alcohol, pregnancy_status)
+  |       Arrays are unioned (allergies, conditions, medications)
+  |       Notes are concatenated with separator
+  |       If secondary has anamnesis_completed=true and primary does not, adopt secondary's date
+  |
+  +-- 6. Merge patient fields:
+  |       patient_tags = UNION of both tag arrays
+  |       patient_total_sessions = primary + secondary
+  |       patient_total_appointments = primary + secondary
+  |       patient_first_contact_at = MIN(primary, secondary)
+  |       patient_last_contact_at = MAX(primary, secondary)
+  |       patient_ai_summary = primary (regenerated async after merge)
+  |       Demographics: primary wins (first_name, last_name, email, date_of_birth, etc.)
+  |
+  +-- 7. Store secondary phone as alternate contact:
+  |       Create PatientNote on primary: "Birlestirildi: eski telefon {secondary.phone}"
+  |
+  +-- 8. Soft-delete secondary patient:
+  |       UPDATE patients SET patient_is_active = false WHERE patient_id = :secondary
+  |
+  +-- 9. Create audit log entry:
+  |       action = 'patient.merge'
+  |       details = { primary_id, secondary_id, secondary_phone, records_moved: { ... } }
+  |
+  v
+Commit transaction
+  |
+  v
+10. Queue async job: regenerate AI summary for primary patient
+  |
+  v
+Return merged primary patient
+```
+
+### 10.3 Edge Cases
+
+| Scenario | Handling |
+|----------|----------|
+| Both patients have medical history with `anamnesis_completed = true` | Primary's anamnesis wins. Secondary's unique data (extra allergies, conditions) is merged in. Note added: "Anamnez birlestirildi" |
+| Circular merge (A -> B, then B -> A) | Rejected -- secondary must be `is_active = true` |
+| Self-merge (same ID for both) | Rejected at validation |
+| Different tenants | Rejected at validation |
+| Secondary has ongoing WhatsApp session | Sessions are re-linked. No active session disruption -- the session continues under the primary patient |
+
+---
+
+## 11. WhatsAppContactProfile Migration
+
+The `whatsapp_contact_profiles` table is **removed** in the new system. All its data lives in `patients` and related tables.
+
+### 11.1 Field Mapping
+
+| Old Field (ContactProfile) | New Location | Notes |
+|---------------------------|-------------|-------|
+| `contact_phone` | `patient_phone` | Direct mapping |
+| `contact_display_name` | `patient_display_name` | Direct mapping |
+| `contact_notes` | `PatientNote` (migrated as first note) | Created as a note with `note_author_id` = system user, `note_text` = contact_notes value |
+| `contact_tags` | `patient_tags` | Direct mapping |
+| `contact_ai_summary` | `patient_ai_summary` | Direct mapping |
+| `contact_preferred_language` | `patient_preferred_language` | Direct mapping. Empty string becomes `"tr"` |
+| `contact_metadata` | Dropped | Was unused JSONB. Any non-empty values are logged before deletion |
+| `contact_first_seen_at` | `patient_first_contact_at` | Direct mapping |
+| `contact_last_seen_at` | `patient_last_contact_at` | Direct mapping |
+| `contact_total_sessions` | `patient_total_sessions` | Direct mapping |
+| `contact_total_messages` | Dropped | Computed from `whatsapp_messages` table at query time. No need to store |
+
+### 11.2 FK Migration
+
+`WhatsAppChat.chat_contact_id` is replaced by `WhatsAppChat.chat_patient_id`:
+
+```
+Migration steps:
+  1. Add column: whatsapp_chats.chat_patient_id (UUID, nullable)
+  2. For each chat with chat_contact_id:
+     a. Look up contact_profile by chat_contact_id
+     b. Find or create Patient by (tenant_id, contact_phone)
+     c. Set chat_patient_id = patient_id
+  3. Drop column: whatsapp_chats.chat_contact_id
+  4. Drop table: whatsapp_contact_profiles
+```
+
+### 11.3 Migration Script (Prisma Migration)
+
+```sql
+-- Step 1: Create patients from contact profiles
+INSERT INTO patients (
+  patient_id, patient_tenant_id, patient_phone, patient_first_name, patient_last_name,
+  patient_display_name, patient_tags, patient_ai_summary, patient_preferred_language,
+  patient_first_contact_at, patient_last_contact_at, patient_total_sessions,
+  patient_created_at, patient_updated_at
+)
+SELECT
+  gen_random_uuid(),
+  contact_tenant_id,
+  contact_phone,
+  CASE
+    WHEN contact_display_name = '' OR contact_display_name = 'Bilinmiyor' THEN 'Bilinmiyor'
+    ELSE split_part(contact_display_name, ' ', 1)
+  END,
+  CASE
+    WHEN contact_display_name = '' OR contact_display_name = 'Bilinmiyor' THEN 'Bilinmiyor'
+    WHEN array_length(string_to_array(contact_display_name, ' '), 1) > 1
+      THEN substring(contact_display_name from position(' ' in contact_display_name) + 1)
+    ELSE 'Bilinmiyor'
+  END,
+  COALESCE(NULLIF(contact_display_name, ''), contact_phone),
+  contact_tags,
+  contact_ai_summary,
+  COALESCE(NULLIF(contact_preferred_language, ''), 'tr'),
+  contact_first_seen_at,
+  contact_last_seen_at,
+  contact_total_sessions,
+  NOW(),
+  NOW()
+FROM whatsapp_contact_profiles
+ON CONFLICT (patient_tenant_id, patient_phone) DO NOTHING;
+
+-- Step 2: Create empty medical histories for migrated patients
+INSERT INTO patient_medical_histories (history_id, history_patient_id, history_created_at, history_updated_at)
+SELECT gen_random_uuid(), patient_id, NOW(), NOW()
+FROM patients
+WHERE NOT EXISTS (
+  SELECT 1 FROM patient_medical_histories WHERE history_patient_id = patients.patient_id
+);
+
+-- Step 3: Migrate contact_notes to patient_notes (where non-empty)
+INSERT INTO patient_notes (note_id, note_patient_id, note_tenant_id, note_author_id, note_text, note_created_at, note_updated_at)
+SELECT
+  gen_random_uuid(),
+  p.patient_id,
+  p.patient_tenant_id,
+  (SELECT user_id FROM users WHERE user_tenant_id = p.patient_tenant_id AND user_role = 'owner' LIMIT 1),
+  cp.contact_notes,
+  cp.contact_created_at,
+  NOW()
+FROM whatsapp_contact_profiles cp
+JOIN patients p ON p.patient_tenant_id = cp.contact_tenant_id AND p.patient_phone = cp.contact_phone
+WHERE cp.contact_notes IS NOT NULL AND cp.contact_notes != '';
+
+-- Step 4: Link chats to patients
+UPDATE whatsapp_chats wc
+SET chat_patient_id = p.patient_id
+FROM whatsapp_contact_profiles cp
+JOIN patients p ON p.patient_tenant_id = cp.contact_tenant_id AND p.patient_phone = cp.contact_phone
+WHERE wc.chat_contact_id = cp.contact_id;
+
+-- Step 5: Drop old column and table (after verification)
+ALTER TABLE whatsapp_chats DROP COLUMN chat_contact_id;
+DROP TABLE whatsapp_contact_profiles;
+```
+
+---
+
+## 12. NestJS Module Structure
+
+```
+src/patients/
+  patients.module.ts              # PatientsModule -- imports PrismaModule, MinioModule, UsersModule
+  patients.controller.ts          # /patients/* endpoints (CRUD, search, merge, timeline)
+  patients.service.ts             # Patient CRUD, search, merge logic, auto-create
+  medical-history.service.ts      # Anamnesis CRUD (1:1 with patient)
+  documents.service.ts            # Upload/delete with MinIO, signed URL generation
+  notes.service.ts                # Note CRUD (create, edit, pin, delete)
+  timeline.service.ts             # Multi-source timeline aggregation (parallel queries + merge)
+  dto/
+    create-patient.dto.ts         # Validation: phone (E.164), first_name, last_name required
+    update-patient.dto.ts         # Partial update (PartialType)
+    update-medical-history.dto.ts # All fields optional
+    create-note.dto.ts            # note_text required
+    upload-document.dto.ts        # doc_type, doc_name required (file via multipart)
+    merge-patients.dto.ts         # primary_patient_id, secondary_patient_id required
+    patient-query.dto.ts          # Pagination, search, filter params
+    timeline-query.dto.ts         # Pagination, type filter
+```
+
+**Module dependencies:**
+
+| Import | Reason |
+|--------|--------|
+| `PrismaModule` | Database access |
+| `MinioModule` | Document upload/download/delete |
+| `UsersModule` | Resolve note authors, validate uploaded_by |
+| `AuditModule` | Log merge operations and sensitive changes |
+| `BullModule` | Queue AI summary regeneration jobs |
+
+**Exports:**
+
+`PatientsService` is exported for use by other modules:
+- `WhatsAppModule` calls `patientsService.findOrCreate()` on incoming messages.
+- `CallsModule` calls `patientsService.findOrCreate()` on inbound calls.
+- `AppointmentsModule` calls `patientsService.incrementAppointmentCount()` on booking.
+
+---
+
+## 13. Feature Flag
+
+No feature flag. The patients module is core functionality, always enabled for all tenants. It replaces `WhatsAppContactProfile` which was also always-on.
+
+---
+
+## 14. Affected Existing Models
+
+The Patient entity becomes the FK target for several existing models. These models gain a `patient_id` foreign key column.
+
+### 14.1 Models with Direct FK
+
+| Model | New Column | Replaces | Notes |
+|-------|-----------|----------|-------|
+| `WhatsAppChat` | `chat_patient_id` (UUID, FK) | `chat_contact_id` | Required migration. See [Section 11](#11-whatsappcontactprofile-migration) |
+| `Appointment` | `appt_patient_id` (UUID, FK) | Phone-based matching | Replaces `appt_patient_phone` as the join key. `appt_patient_phone` is kept for display but is no longer the primary link |
+| `Lead` | `lead_patient_id` (UUID, nullable FK) | -- | Optional. Linked when a patient record exists for the lead's phone. Null for leads that have not yet become patients |
+
+### 14.2 Models with Indirect Patient Resolution
+
+| Model | Resolution Path | Notes |
+|-------|----------------|-------|
+| `OperatorRequest` | `opreq_session_id` -> `WhatsAppSession` -> `WhatsAppChat.chat_patient_id` | No direct FK needed. Resolved via JOINs |
+| `Call` | `call_caller_phone` matched against `patient_phone` at query time | No FK. Phone matching is done in the timeline query. Adding a FK would require resolving patient on every inbound call before the call connects (too slow) |
+| `WhatsAppSession` | `session_chat_id` -> `WhatsAppChat.chat_patient_id` | No direct FK needed. Resolved via one JOIN through chat |
+| `WhatsAppMessage` | `msg_chat_id` -> `WhatsAppChat.chat_patient_id` | No direct FK needed. Messages are always accessed in chat context |
+
+### 14.3 Appointment Model Changes
+
+```prisma
+// Before (current):
+model Appointment {
+  appt_patient_name   String   // Free text name
+  appt_patient_phone  String   // E.164 phone -- the only link to patient
+  // ...
+}
+
+// After (with patients):
+model Appointment {
+  appt_patient_id     String   // FK to patients (required for new appointments)
+  appt_patient_name   String   // Kept for display (denormalized)
+  appt_patient_phone  String   // Kept for Google Calendar events and SMS
+  // ...
+
+  patient Patient @relation(fields: [appt_patient_id], references: [patient_id])
+}
+```
+
+`appt_patient_name` and `appt_patient_phone` are kept as denormalized fields because:
+- Google Calendar event creation needs the name and phone as plain strings.
+- SMS reminders need the phone number without a JOIN.
+- Historical appointments (pre-migration) may not have a `patient_id` -- the denormalized fields ensure they remain displayable.
+
+### 14.4 WhatsAppChat Model Changes
+
+```prisma
+// Before (current):
+model WhatsAppChat {
+  chat_contact_id   String?  // FK to whatsapp_contact_profiles
+  // ...
+}
+
+// After (with patients):
+model WhatsAppChat {
+  chat_patient_id   String?  // FK to patients
+  // ...
+
+  patient Patient? @relation(fields: [chat_patient_id], references: [patient_id])
+}
+```
+
+`chat_patient_id` is nullable to handle edge cases where a chat exists but the patient record has not yet been created (should not happen in normal flow, but defensive).
+
+### 14.5 Lead Model Changes
+
+```prisma
+// Before (current):
+model Lead {
+  lead_phone         String   // E.164 phone
+  // ...
+}
+
+// After (with patients):
+model Lead {
+  lead_patient_id    String?  // FK to patients (nullable)
+  lead_phone         String   // Kept -- leads may exist before patient creation
+  // ...
+
+  patient Patient? @relation(fields: [lead_patient_id], references: [patient_id])
+}
+```
+
+`lead_patient_id` is nullable because leads can exist before a patient record is created (e.g., a lead from a campaign that has not yet contacted the clinic). When the lead's phone matches an existing patient, the link is established.