elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/21-BEFORE-AFTER-PHOTOS.md

@@ -0,0 +1,519 @@
+# Before/After Patient Photos
+
+> Structured photo documentation linked to patients and treatment plans -- consultation photos, progress tracking, and before/after comparisons for aesthetic and dental clinics.
+> Last updated: 2026-03-29
+
+---
+
+## 1. Overview
+
+Before/after photos are essential for aesthetic and dental clinics. This is **not** random media from WhatsApp chat -- it is structured photo documentation linked to patients and treatment plans.
+
+### Use Cases
+
+| Use Case | Description |
+|----------|-------------|
+| Before photos | Taken at consultation, before any treatment begins |
+| Progress photos | Taken during treatment (e.g., between sessions) |
+| After photos | Taken at treatment completion (1 week, 1 month, 3 months) |
+| Comparison grids | Side-by-side before/after on patient detail page, matched by angle |
+| Portfolio / case documentation | Future: marketing material with patient consent |
+
+### How It Works
+
+```
+Patient visits clinic
+  |
+  v
+Staff opens patient detail -> Photos tab -> "Add Photo Set"
+  |
+  v
+Selects type (before / after_1week / progress / ...)
+Optionally links to a treatment plan
+  |
+  v
+Uploads multiple images (front, left, right, smile, ...)
+  |
+  v
+Each image -> MinIO (original + thumbnail)
+  |
+  v
+Later: staff adds after photos
+  |
+  v
+Frontend displays comparison grid (before front vs. after front, etc.)
+```
+
+---
+
+## 2. Data Model
+
+Two tables: `patient_photo_sets` (a group of related photos taken at a point in time) and `patient_photos` (individual images within a set).
+
+### 2.1 patient_photo_sets
+
+**Purpose:** A logical group of photos taken at a specific point in a patient's treatment timeline. For example, "Before - Front/Left/Right" or "1 Month After - Front/Smile".
+
+```prisma
+model PatientPhotoSet {
+  photoset_id                String   @id @default(uuid())
+  photoset_patient_id        String
+  photoset_tenant_id         String
+  photoset_clinic_id         String?
+  photoset_treatment_plan_id String?
+  photoset_type              String
+  photoset_label             String   @default("")
+  photoset_taken_at          DateTime @default(now())
+  photoset_taken_by          String?
+  photoset_notes             String   @default("")
+  photoset_created_at        DateTime @default(now())
+  photoset_updated_at        DateTime @updatedAt
+
+  patient       Patient        @relation(fields: [photoset_patient_id], references: [patient_id], onDelete: Cascade)
+  tenant        Tenant         @relation(fields: [photoset_tenant_id], references: [tenant_id], onDelete: Cascade)
+  clinic        Clinic?        @relation(fields: [photoset_clinic_id], references: [clinic_id], onDelete: SetNull)
+  treatmentPlan TreatmentPlan? @relation(fields: [photoset_treatment_plan_id], references: [plan_id], onDelete: SetNull)
+  takenBy       User?          @relation("PhotosTakenBy", fields: [photoset_taken_by], references: [user_id], onDelete: SetNull)
+  photos        PatientPhoto[]
+
+  @@index([photoset_patient_id, photoset_taken_at(sort: Desc)])
+  @@index([photoset_treatment_plan_id])
+  @@index([photoset_tenant_id, photoset_type])
+  @@map("patient_photo_sets")
+}
+```
+
+**Columns:**
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `photoset_id` | UUID | Yes | `uuid()` | Primary key |
+| `photoset_patient_id` | UUID | Yes | -- | FK to `patients`. The patient these photos belong to |
+| `photoset_tenant_id` | UUID | Yes | -- | FK to `tenants`. Tenant isolation |
+| `photoset_clinic_id` | UUID | No | `null` | FK to `clinics`. Which clinic took the photos |
+| `photoset_treatment_plan_id` | UUID | No | `null` | FK to `treatment_plans`. Optional link to treatment plan |
+| `photoset_type` | String | Yes | -- | Photo set type: `before`, `after_1week`, `after_1month`, `after_3months`, `progress`, `other` |
+| `photoset_label` | String | Yes | `""` | Free-form label for custom naming. E.g., "Pre-op", "6 ay sonrasi", "Kontrol 2" |
+| `photoset_taken_at` | DateTime | Yes | `now()` | When the photos were physically taken (not when uploaded) |
+| `photoset_taken_by` | UUID | No | `null` | FK to `users`. Staff member who took the photos |
+| `photoset_notes` | String | Yes | `""` | Free-form notes about this photo set |
+| `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, newest first |
+| `idx_photosets_treatment` | `photoset_treatment_plan_id` | List all photo sets for a treatment plan |
+| `idx_photosets_tenant_type` | `(photoset_tenant_id, photoset_type)` | Filter by type within a tenant |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | patients | `photoset_patient_id` | Parent patient (cascade delete) |
+| belongs_to | tenants | `photoset_tenant_id` | Tenant isolation (cascade delete) |
+| belongs_to | clinics | `photoset_clinic_id` | Clinic that took the photos (nullable, set null on delete) |
+| belongs_to | treatment_plans | `photoset_treatment_plan_id` | Linked treatment plan (nullable, set null on delete) |
+| belongs_to | users (PhotosTakenBy) | `photoset_taken_by` | Staff who took photos (nullable, set null on delete) |
+| has_many | patient_photos | -- | Individual photos in this set |
+
+### 2.2 patient_photos
+
+**Purpose:** An individual image within a photo set. Stores the MinIO key for the original file and its thumbnail, plus metadata like angle and sort order.
+
+```prisma
+model PatientPhoto {
+  photo_id            String   @id @default(uuid())
+  photo_set_id        String
+  photo_angle         String   @default("")
+  photo_media_key     String
+  photo_thumbnail_key String?
+  photo_caption       String   @default("")
+  photo_sort_order    Int      @default(0)
+  photo_created_at    DateTime @default(now())
+
+  photoSet PatientPhotoSet @relation(fields: [photo_set_id], references: [photoset_id], onDelete: Cascade)
+
+  @@index([photo_set_id, photo_sort_order])
+  @@map("patient_photos")
+}
+```
+
+**Columns:**
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `photo_id` | UUID | Yes | `uuid()` | Primary key |
+| `photo_set_id` | UUID | Yes | -- | FK to `patient_photo_sets`. Parent set |
+| `photo_angle` | String | Yes | `""` | Standardized angle: `front`, `left`, `right`, `top`, `bottom`, `smile`, `closeup`, `other` |
+| `photo_media_key` | String | Yes | -- | MinIO object key for the original image |
+| `photo_thumbnail_key` | String | No | `null` | MinIO object key for the thumbnail (generated on upload) |
+| `photo_caption` | String | Yes | `""` | Optional caption for this specific photo |
+| `photo_sort_order` | Int | Yes | `0` | Display order within the set |
+| `photo_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+
+**Indexes:**
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `photo_id` | PK lookup |
+| `idx_photos_set_order` | `(photo_set_id, photo_sort_order)` | Photos within a set, sorted for display |
+
+**Relations:**
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | patient_photo_sets | `photo_set_id` | Parent set (cascade delete -- deleting a set removes all photos) |
+
+### 2.3 Design Decisions
+
+- **Two tables (set + photos):** A photo set is a logical group taken at a point in time. Individual photos have their own metadata (angle, sort order, caption). This separation enables comparison grids: match "before front" with "after front" across sets.
+- **`photoset_type` is a String, not a Prisma enum:** Clinics may need custom types beyond the standard set. A string avoids database migrations for new types. Validation happens at the application layer.
+- **`photoset_taken_at` is separate from `created_at`:** Photos are often taken on a device and uploaded later. The taken date is the medically relevant timestamp, not the upload date.
+- **`photoset_treatment_plan_id` is optional:** Photos can exist without a treatment plan. Consultation photos are often taken before a treatment plan exists.
+- **`photo_angle` standardizes positioning:** The frontend can align "front" photos from a before set and an after set side by side. Without standardized angles, comparison views would require manual matching.
+- **Cascade delete from set to photos:** A photo set and its photos are a unit. Deleting the set always deletes the photos. No orphaned photo records.
+- **Cascade delete from patient to sets:** When a patient is deleted (KVKK), all their photo sets are automatically removed from the database. MinIO cleanup is a separate step.
+- **`photo_thumbnail_key` is nullable:** The thumbnail is generated asynchronously on upload. If generation fails, the original image is still available.
+
+---
+
+## 3. MinIO Storage
+
+All patient photos are stored in MinIO. The database stores only the object key (a string). See [18-FILE-STORAGE.md](18-FILE-STORAGE.md) for MinIO infrastructure details.
+
+### 3.1 Path Pattern
+
+```
+{tenantId}/patients/{patientId}/photos/{photosetId}/{photoId}.{ext}
+{tenantId}/patients/{patientId}/photos/{photosetId}/{photoId}_thumb.{ext}
+```
+
+Example:
+
+```
+abc-tenant-123/patients/patient-456/photos/set-789/photo-001.jpg
+abc-tenant-123/patients/patient-456/photos/set-789/photo-001_thumb.jpg
+```
+
+### 3.2 Access Control
+
+- All files served via pre-signed URLs with a 1-hour TTL. No public access.
+- Tenant isolation enforced at the application layer: all keys start with `{tenantId}/`.
+- Server-side encryption (SSE-S3) applied transparently by MinIO.
+
+### 3.3 Thumbnail Generation
+
+Thumbnails are generated server-side on upload using `sharp`:
+
+```typescript
+import sharp from 'sharp';
+
+const thumbnail = await sharp(originalBuffer)
+  .resize({ width: 400, withoutEnlargement: true })
+  .jpeg({ quality: 80 })
+  .toBuffer();
+```
+
+- Width: 400px (height auto-scaled to preserve aspect ratio)
+- Format: JPEG at 80% quality regardless of original format
+- `withoutEnlargement: true` prevents upscaling small images
+- Thumbnails are used in list views and grid previews to avoid loading full-resolution images
+
+### 3.4 KVKK Deletion
+
+Patient photos are medical images (PHI). On KVKK data deletion or patient hard delete:
+
+1. Cascade delete removes all `PatientPhoto` and `PatientPhotoSet` records from PostgreSQL
+2. MinIO cleanup removes all objects under the patient photos prefix:
+
+```typescript
+await this.minioService.removeObjects(
+  `${tenantId}/patients/${patientId}/photos/`
+);
+```
+
+This is added to the existing KVKK deletion workflow alongside WhatsApp media and other patient data.
+
+---
+
+## 4. Comparison View
+
+The primary value of structured photo sets is the before/after comparison grid on the patient detail page.
+
+### 4.1 Query Flow
+
+```
+Frontend: GET /patients/:id/photo-sets?treatmentPlanId=xxx
+  |
+  v
+Backend returns sets sorted by taken_at, each containing photos sorted by sort_order
+  |
+  v
+Frontend groups sets by type:
+  - before
+  - after_1week
+  - after_1month
+  - after_3months
+  - progress
+  |
+  v
+Within each type pair (e.g., before + after_1month),
+  match photos by angle (front-to-front, left-to-left)
+  |
+  v
+Display in comparison grid or slider
+```
+
+### 4.2 Angle Matching
+
+The frontend matches photos across sets using the `photo_angle` field:
+
+| Before Set | After Set | Result |
+|-----------|-----------|--------|
+| front | front | Side-by-side comparison |
+| left | left | Side-by-side comparison |
+| smile | smile | Side-by-side comparison |
+| closeup | (no match) | Shown alone |
+
+Photos without a matching angle in the other set are displayed separately. The comparison view does not require every angle to be present in both sets.
+
+### 4.3 API Response Shape
+
+```typescript
+// GET /patients/:id/photo-sets?treatmentPlanId=xxx
+{
+  data: [
+    {
+      photoset_id: "set-001",
+      photoset_type: "before",
+      photoset_label: "Ilk muayene",
+      photoset_taken_at: "2026-03-15T10:00:00Z",
+      photoset_notes: "",
+      photos: [
+        {
+          photo_id: "photo-001",
+          photo_angle: "front",
+          photo_url: "https://minio.../signed-url",        // pre-signed GET URL
+          photo_thumbnail_url: "https://minio.../signed-url", // thumbnail signed URL
+          photo_caption: "",
+          photo_sort_order: 0
+        },
+        {
+          photo_id: "photo-002",
+          photo_angle: "left",
+          photo_url: "https://minio.../signed-url",
+          photo_thumbnail_url: "https://minio.../signed-url",
+          photo_caption: "",
+          photo_sort_order: 1
+        }
+      ]
+    },
+    {
+      photoset_id: "set-002",
+      photoset_type: "after_1month",
+      photoset_label: "1 ay sonra",
+      photoset_taken_at: "2026-04-15T10:00:00Z",
+      photos: [ ... ]
+    }
+  ],
+  total: 2
+}
+```
+
+The backend resolves MinIO keys to signed URLs before returning the response. The frontend never sees raw MinIO keys.
+
+---
+
+## 5. Upload Flow
+
+### 5.1 Step-by-Step
+
+```
+Staff opens patient detail -> Photos tab -> "Add Photo Set"
+  |
+  v
+1. Staff selects type (before / after_1week / after_1month / after_3months / progress / other)
+   Optionally links a treatment plan
+   Sets taken_at date (defaults to now)
+     |
+     v
+2. POST /patients/:id/photo-sets
+   Body: { type, label?, treatment_plan_id?, taken_at?, notes? }
+   Returns: { photoset_id, ... }
+     |
+     v
+3. Staff uploads images (drag & drop or file picker, multiple at once)
+   For each image:
+     |
+     v
+   a. Frontend sends file to POST /patients/:id/photo-sets/:setId/photos (multipart/form-data)
+     |
+     v
+   b. Backend validates file (type: JPEG/PNG/WEBP, max size: 20MB)
+     |
+     v
+   c. Backend uploads original to MinIO:
+      Key: {tenantId}/patients/{patientId}/photos/{setId}/{photoId}.{ext}
+     |
+     v
+   d. Backend generates thumbnail (sharp, 400px width, JPEG 80%)
+     |
+     v
+   e. Backend uploads thumbnail to MinIO:
+      Key: {tenantId}/patients/{patientId}/photos/{setId}/{photoId}_thumb.{ext}
+     |
+     v
+   f. Backend creates PatientPhoto record with media_key and thumbnail_key
+     |
+     v
+   g. Returns photo record with signed URLs
+     |
+     v
+4. Staff optionally sets angle and caption per photo via:
+   PUT /patients/:id/photo-sets/:setId/photos/:photoId
+     |
+     v
+5. Done. Photos are immediately visible on the patient detail page.
+```
+
+### 5.2 File Validation
+
+| Check | Rule | Error |
+|-------|------|-------|
+| MIME type | `image/jpeg`, `image/png`, `image/webp` only | 400: Unsupported file type |
+| File size | Maximum 20 MB per image | 400: File too large |
+| File count | Maximum 20 photos per set | 400: Too many photos in set |
+
+HEIC files (common from iPhones) are converted to JPEG server-side using `sharp` before storage.
+
+---
+
+## 6. Operator Workflow Integration
+
+The existing operator workflow (see [05-OPERATOR-WORKFLOW.md](05-OPERATOR-WORKFLOW.md)) forwards patient photos from WhatsApp to a doctor via the `forward_to_operator` tool. These are unstructured media messages in a chat context.
+
+The before/after photo system is separate and structured -- it is clinic-managed documentation, not chat media.
+
+**Future enhancement:** When the operator workflow forwards patient photos to a doctor, those WhatsApp media images could optionally be saved as a patient photo set automatically. This would bridge the gap between chat-originated media and structured patient records. For now, the two systems are independent.
+
+---
+
+## 7. API Endpoints
+
+All endpoints are nested under `/patients/:id` and require the patient to belong to the current user's tenant and accessible clinics.
+
+| Method | Path | Permission | Description |
+|--------|------|------------|-------------|
+| GET | `/patients/:id/photo-sets` | `patients:read` | List photo sets for a patient. Filterable by `type` and `treatmentPlanId`. Returns sets with nested photos (signed URLs). Sorted by `taken_at` descending |
+| POST | `/patients/:id/photo-sets` | `patients:update` | Create a new photo set (metadata only, no files). Body: `{ type, label?, treatment_plan_id?, taken_at?, taken_by?, notes? }` |
+| GET | `/patients/:id/photo-sets/:setId` | `patients:read` | Single photo set with all photos (signed URLs) |
+| PUT | `/patients/:id/photo-sets/:setId` | `patients:update` | Update set metadata: type, label, notes, taken_at, treatment_plan_id |
+| DELETE | `/patients/:id/photo-sets/:setId` | `patients:update` | Delete set + all photos. Removes MinIO objects and database records |
+| POST | `/patients/:id/photo-sets/:setId/photos` | `patients:update` | Upload a photo to a set. Multipart form data with single file. Returns photo record with signed URLs |
+| PUT | `/patients/:id/photo-sets/:setId/photos/:photoId` | `patients:update` | Update photo metadata: angle, caption, sort_order |
+| DELETE | `/patients/:id/photo-sets/:setId/photos/:photoId` | `patients:update` | Delete a single photo. Removes original + thumbnail from MinIO |
+
+### Query Parameters for GET `/patients/:id/photo-sets`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | String | Filter by set type: `before`, `after_1week`, `after_1month`, `after_3months`, `progress`, `other` |
+| `treatmentPlanId` | UUID | Filter by linked treatment plan |
+| `page` | Int | Page number (default 1) |
+| `limit` | Int | Items per page (default 50) |
+
+---
+
+## 8. Permissions
+
+Photo management uses existing patient permissions. No separate photo permission is needed.
+
+| Permission | Photo Operations |
+|------------|-----------------|
+| `patients:read` | View photo sets, view individual photos (signed URLs) |
+| `patients:update` | Create/update/delete photo sets, upload/update/delete photos |
+
+**Rationale:** Photos are patient data. If you can view a patient, you can view their photos. If you can update a patient, you can manage their photos. Adding a separate `photos:*` permission would complicate the permission model without meaningful access control benefit -- anyone working with a patient's clinical data needs to see their photos.
+
+---
+
+## 9. NestJS Module Structure
+
+Photo management is part of the `PatientsModule`, not a separate module. Photos are tightly coupled to patients.
+
+```
+src/patients/
+  patients.module.ts           # Imports MinioModule, registers photo service
+  patients.controller.ts       # Patient CRUD endpoints
+  photo-sets.controller.ts     # Photo set + photo endpoints (nested under /patients/:id)
+  photo-sets.service.ts        # Photo set CRUD, photo upload, thumbnail generation, MinIO operations
+  dto/
+    create-photo-set.dto.ts    # { type, label?, treatment_plan_id?, taken_at?, taken_by?, notes? }
+    update-photo-set.dto.ts    # Partial of create
+    update-photo.dto.ts        # { angle?, caption?, sort_order? }
+    photo-set-query.dto.ts     # { type?, treatmentPlanId?, page?, limit? }
+```
+
+### Service Responsibilities
+
+`PhotoSetsService` handles:
+
+1. **Photo set CRUD** -- create, read, update, delete sets with tenant scoping
+2. **Photo upload** -- accept multipart file, validate, upload to MinIO, generate thumbnail, create record
+3. **Signed URL resolution** -- convert MinIO keys to pre-signed URLs when returning photo data
+4. **Photo metadata updates** -- angle, caption, sort order
+5. **MinIO cleanup** -- delete objects when photos or sets are removed
+6. **KVKK support** -- bulk delete all photos for a patient (called by KVKK deletion workflow)
+
+### Dependencies
+
+```typescript
+@Module({
+  imports: [MinioModule],  // For file storage
+  controllers: [PatientsController, PhotoSetsController],
+  providers: [PatientsService, PhotoSetsService],
+  exports: [PatientsService, PhotoSetsService],
+})
+export class PatientsModule {}
+```
+
+---
+
+## 10. KVKK Considerations
+
+Patient photos are medical images and classified as Personal Health Information (PHI) under KVKK (Turkish data protection law).
+
+### What Must Be Deleted
+
+When a KVKK data deletion request is executed for a patient:
+
+| Data | Location | Deletion Method |
+|------|----------|-----------------|
+| `PatientPhotoSet` records | PostgreSQL | Cascade delete from patient |
+| `PatientPhoto` records | PostgreSQL | Cascade delete from photo set |
+| Original images | MinIO | `removeObjects({tenantId}/patients/{patientId}/photos/)` |
+| Thumbnails | MinIO | Same prefix removal (thumbnails are in the same directory) |
+
+### Integration with KVKK Workflow
+
+The existing KVKK deletion workflow runs these steps. Patient photos are added as an additional cleanup step:
+
+```typescript
+// In KVKK deletion handler:
+async deletePatientData(tenantId: string, patientId: string) {
+  // ... existing deletion steps ...
+
+  // Delete patient photos from MinIO
+  await this.minioService.removeObjects(
+    `${tenantId}/patients/${patientId}/photos/`
+  );
+
+  // PostgreSQL records deleted via cascade when patient record is removed
+}
+```
+
+No separate audit trail is needed for photo deletion -- the KVKK deletion audit log covers the entire patient data removal.