elevenlabs-webhook-nodejs 1.0.0

package/docs/MIGRATION_GUIDE.md

@@ -0,0 +1,96 @@
+# Production Migration Guide
+
+> Required migrations for the WhatsApp Agent session-centric architecture and agent reference updates.
+
+---
+
+## Prerequisites
+
+- Node.js 18+ with `tsx` available (`npx tsx`)
+- `MONGODB_URI` set in `.env` pointing to the target database
+- Deploy the new code **before** running migrations (new models must be registered)
+
+---
+
+## Migration 1: Session Architecture (`migrate-sessions.ts`)
+
+Migrates from the old chat-centric architecture (session fields embedded on `WhatsAppChat`) to the new session-centric architecture (`WhatsAppSession` collection).
+
+### What it does
+
+1. Creates `WhatsAppSession` documents from old embedded chat fields (`mode`, `session_status`, `taken_over_by`, etc.)
+2. Backfills `session_id` on existing `WhatsAppMessage` documents
+3. Sets `is_closed` and `active_session_id` on `WhatsAppChat` documents
+4. Removes 10 old embedded fields from chats via `$unset`
+
+### Fields removed from `WhatsAppChat`
+
+`mode`, `session_status`, `session_started_at`, `session_grace_deadline`, `session_resolved_by`, `taken_over_by`, `taken_over_at`, `elevenlabs_conversation_id`, `elevenlabs_conversation_created_at`, `elevenlabs_last_interaction_at`
+
+### Run
+
+```bash
+# Preview changes (no writes)
+npx tsx scripts/migrate-sessions.ts --dry-run
+
+# Execute migration
+npx tsx scripts/migrate-sessions.ts
+```
+
+### Idempotent
+
+Skips chats that already have `active_session_id` set. Safe to re-run.
+
+---
+
+## Migration 2: Agent Reference (`migrate-agent-ref.ts`)
+
+Converts the old `elevenlabs_agent_id` string in tenant WhatsApp settings to an `agent_id` ObjectId reference to the `Agent` model.
+
+### What it does
+
+1. Finds tenants with `settings.whatsapp_agent.elevenlabs_agent_id` set
+2. Looks up the matching `Agent` document (by ElevenLabs ID, or falls back to tenant's active agent)
+3. Sets `settings.whatsapp_agent.agent_id` to the Agent's ObjectId
+4. Removes the old `elevenlabs_agent_id` field
+
+### Run
+
+```bash
+# Preview changes (no writes)
+npx tsx scripts/migrate-agent-ref.ts --dry-run
+
+# Execute migration
+npx tsx scripts/migrate-agent-ref.ts
+```
+
+### Idempotent
+
+Skips tenants that already have `agent_id` set. Safe to re-run.
+
+---
+
+## Deployment Order
+
+1. **Deploy** new code to production
+2. **Run** `migrate-sessions.ts` (creates the `WhatsAppSession` collection the new code depends on)
+3. **Run** `migrate-agent-ref.ts` (needs `Agent` documents to resolve references)
+4. **Verify** via dry-run or DB check that migrations completed
+
+```bash
+# Full sequence on prod
+MONGODB_URI=mongodb+srv://... npx tsx scripts/migrate-sessions.ts --dry-run
+MONGODB_URI=mongodb+srv://... npx tsx scripts/migrate-sessions.ts
+MONGODB_URI=mongodb+srv://... npx tsx scripts/migrate-agent-ref.ts --dry-run
+MONGODB_URI=mongodb+srv://... npx tsx scripts/migrate-agent-ref.ts
+```
+
+---
+
+## Rollback
+
+Both migrations are forward-only. The old embedded fields are removed via `$unset`. If you need to rollback:
+
+- The new code is backward-compatible with missing sessions (startup recovery will handle `waiting` sessions)
+- Old frontend code would need the embedded fields restored manually from the `WhatsAppSession` documents
+- In practice, rollback is not recommended — fix forward instead

package/docs/MISSINGS_REPORT.md

@@ -0,0 +1,507 @@
+# NestJS Architecture Audit -- Gaps Report
+
+> Generated: 2026-04-03
+> Scope: All architecture docs (00--21) vs. NestJS source at `nestjs/src/`
+> Reference: `docs/IMPLEMENTATION_STATUS.md` cross-checked
+
+---
+
+## 1. Documented Features NOT Implemented
+
+### 1.1 WhatsApp AI Engine (Doc 04)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| ElevenLabs WebSocket connection lifecycle (signed URL, handshake, keepalive, lazy reconnect) | 04 Section 10 | **P0** |
+| `triggerAiResponse()` -- send combined messages to ElevenLabs via WS `user_message` | 04 Section 9-10 | **P0** |
+| `buildChatContext()` -- timeline builder for `contextual_update` | 04 Section 4 "Chat Context Building" | **P0** |
+| Grace period BullMQ processor (`whatsapp:grace`) -- verify session state, activate AI, replay pending messages | 04 Section 1 | **P0** |
+| Message buffer BullMQ processor (`whatsapp:message-buffer`) -- collect + combine pending messages, send to AI | 04 Section 1 | **P0** |
+| Session cleanup sweep processor (`whatsapp:session-cleanup`) -- 2h inactivity auto-resolve | 04 Section 1 | **P0** |
+| Cost sweep processor (`whatsapp:cost-sweep`) -- fetch ElevenLabs conversation costs | 04 Section 12 | **P1** |
+| Profile update processor (`whatsapp:profile-update`) -- AI summary regeneration via AIModule | 04 Section 8 | **P1** |
+| Session labels processor (`whatsapp:session-labels`) -- sentiment + category via AIModule | 04 Section 8 | **P1** |
+| Message cleanup processor (`whatsapp:message-cleanup`) -- delete old messages + MinIO media | 04 Section 12 | **P1** |
+| Operator expiry processor (`whatsapp:operator-expiry`) -- expire pending requests, notify AI | 05 Section 4 | **P1** |
+| Dynamic variables sent to ElevenLabs (`user_summary`, `current_date`, `continuation_directive`) | 04 Section 4 | **P0** |
+| Chat continuity on WS reconnection (`continuation_directive` builder) | 04 Section 5 | **P1** |
+| AI shift scheduling check (outside clinic hours logic) | 04 Section 6 | **P1** |
+| Session recovery on startup (re-evaluate stuck `waiting` sessions) | 04 Section 13 | **P1** |
+| Voice transcription (STT) -- download audio from Meta, send to ElevenLabs Scribe | 04 Section 2 Step 3 | **P1** |
+| Message deduplication on echo (match by `msg_external_id` or text+timestamp fallback) | 04 Section 12 | **P0** |
+| System message filtering (40+ regex patterns for non-conversational messages) | 04 Section 2 Step 2 | **P0** |
+| Patient find-or-create on first contact | 04 Section 2 Step 5 | **P0** |
+| Fixed first message sending on new session | 04 Section 11 | **P1** |
+| Self-sent message handling (resolve `waiting` as `human`, auto-switch `active` sessions) | 04 Section 10 | **P0** |
+| Redis WS connection state (`ws:conn:{chatId}` hash with agentId, sessionId, etc.) | 04 Section 7 | **P0** |
+
+**Status in code:** `whatsapp-agent.service.ts` has method signatures but all core methods contain only `// TODO` comments. All 8 WhatsApp BullMQ processors are stubs (`process()` body is just a TODO comment).
+
+### 1.2 Operator Workflow (Doc 05)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `forwardToOperator()` -- find media, generate REF code, forward via Meta API with 500ms delay | 05 Section 2 | **P0** |
+| `handleOperatorReply()` -- detect operator phone, extract REF code, update OperatorRequest, inject response | 05 Section 3 | **P0** |
+| `injectOperatorResponse()` -- recreate WS if dead, send contextual_update + user_message | 05 Section 3 | **P0** |
+| Forward conversation to operator (text-only variant) | 05 Section 5 | **P1** |
+| Send example photo from MinIO | 05 Section 6 | **P1** |
+| REF code generation (random 4-char alphanumeric with collision check) | 05 Section 8 | **P0** |
+| Operator reply detection in webhook handler (sender phone check + REF code regex) | 05 Section 3 | **P0** |
+
+**Status in code:** `operator.service.ts` has method skeletons but `forwardToOperator()` says `// TODO: Forward media to operator phone via Meta Business API`, `handleOperatorReply()` says `// TODO: Inject operator response into ElevenLabs conversation`, `handleExpiredRequest()` says `// TODO: Notify AI to inform patient`.
+
+### 1.3 Client Tool Handlers (Doc 10) -- ALL 13 are TODO stubs
+
+| Tool | File | Priority |
+|------|------|----------|
+| `check_availability` | `tools/handlers/calendar.tools.ts` | **P0** |
+| `reserve_slot` | `tools/handlers/calendar.tools.ts` | **P0** |
+| `list_reservations` | `tools/handlers/calendar.tools.ts` | **P0** |
+| `cancel_reservation` | `tools/handlers/calendar.tools.ts` | **P0** |
+| `reschedule_reservation` | `tools/handlers/calendar.tools.ts` | **P0** |
+| `check_patient_history` | `tools/handlers/patient.tools.ts` | **P1** |
+| `call_patient` | `tools/handlers/patient.tools.ts` | **P1** |
+| `forward_to_operator` | `tools/handlers/operator.tools.ts` | **P0** |
+| `forward_conversation` | `tools/handlers/operator.tools.ts` | **P1** |
+| `send_example_photo` | `tools/handlers/operator.tools.ts` | **P1** |
+| `confirm_appointment_validation` | `tools/handlers/validation.tools.ts` | **P1** |
+| `request_payment` | `tools/handlers/payment.tools.ts` | **STUB** |
+| `send_sms` | `tools/handlers/notification.tools.ts` | **STUB** |
+
+**Status in code:** All handler methods have `@Tool()` decorators with proper metadata (name, description, parameters, requiredFeatures, channels) but the method bodies are `// TODO: Delegate to ...` stubs that return placeholder results.
+
+### 1.4 WebSocket Gateway (Doc 17) -- NOT CREATED
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `EventsGateway` (`@WebSocketGateway` with Socket.IO) | 17 Section 2 | **P0** |
+| JWT authentication on WS handshake | 17 Section 2.2 | **P0** |
+| Tenant room joining (`tenant:{tenantId}`) | 17 Section 2.3 | **P0** |
+| Redis adapter for multi-instance support | 17 Section 2.4 | **P1** |
+| 11 event types (`chat:new`, `chat:message`, `chat:session-status`, `chat:typing`, `call:new`, `call:completed`, `lead:new`, `appointment:new`, `appointment:cancelled`, `notification`, `validation:status`) | 17 Section 3 | **P0** |
+| `@OnEvent` listeners that broadcast to tenant rooms | 17 Section 3.5 | **P0** |
+| Typing indicator handler (`@SubscribeMessage('typing')`) | 17 Section 7 | **P2** |
+| `LiveChatService` for human message sending | 17 Section 8 | **P0** |
+| `POST /whatsapp/chats/:chatId/send-media` (multipart upload, MinIO storage, send via Meta API) | 17 Section 4.5 | **P1** |
+
+**Status in code:** No `events.gateway.ts` file exists anywhere. No `live-chat.service.ts` exists. Packages `@nestjs/websockets`, `@nestjs/platform-socket.io`, `socket.io`, `@socket.io/redis-adapter` are installed in `package.json` but unused. The WhatsApp controller has `takeover`, `release`, `resolve`, and `send message` endpoints, but there is no `send-media` endpoint and no real-time event broadcasting.
+
+### 1.5 Prisma Tenant-Scoping Middleware (Doc 00, 12)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| Prisma `$use` middleware that auto-injects `WHERE tenantId` on every query | 00 Rule 1, 12 "Tenant Data Isolation" | **P0** |
+| Cross-tenant access requiring `superadmin` role + explicit `allTenants: true` flag | 00 Rule 1 | **P0** |
+
+**Status in code:** No `prisma.$use()` call exists anywhere. `IMPLEMENTATION_STATUS.md` acknowledges: "Tenant-scoped queries (Prisma middleware) -- Structure ready, middleware TODO". Each service currently manually adds `tenantId` WHERE clauses, which is error-prone and not enforced.
+
+### 1.6 Request Context (AsyncLocalStorage) (Doc 13)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `RequestContextInterceptor` with `AsyncLocalStorage` for correlation IDs | 13 "AsyncLocalStorage for Request Context Propagation" | **P1** |
+| `X-Request-Id` header propagation across service calls and queue jobs | 13 Section "Structured Log Format" | **P1** |
+| Correlation ID attached to all log entries | 13 Section "Structured Log Format" | **P1** |
+
+**Status in code:** No `AsyncLocalStorage` usage anywhere in the codebase. No `RequestContextInterceptor` exists. No `src/common/interceptors/` directory exists at all.
+
+### 1.7 HTTP Exception Filter (Doc 00)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `HttpExceptionFilter` for standardized error responses | 00 Section 6 "Common (Shared)" | **P1** |
+
+**Status in code:** No `src/common/filters/` directory exists. No global exception filter is registered.
+
+### 1.8 ElevenLabs Post-Call Webhook Processing (Doc 08)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `elevenlabs:webhook` BullMQ processor -- full pipeline: find agent, resolve clinic, generate AI summary, create Call + CallDetail, generate labels, log billing, create Lead, send WA notification, send SMS, emit events | 08 Section 3 | **P0** |
+| `elevenlabs:tools` BullMQ processor -- tool webhook processing during voice calls | 08 Section 4 | **P0** |
+
+**Status in code:** `elevenlabs-webhook.processor.ts` has `// TODO: Implement post-call processing`. The `elevenlabs-tool.controller.ts` returns `{ result: 'not_implemented' }`.
+
+### 1.9 Outbound Campaign Dispatch (Doc 09)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `outbound-campaigns:dispatch` processor -- call dispatch with time window, concurrency, retry logic | 09 Section 5 | **P1** |
+| `outbound-campaigns:sync` processor -- status sync from ElevenLabs | 09 Section 9 | **P1** |
+
+**Status in code:** `campaign-dispatch.processor.ts` has `// TODO: Implement outbound call dispatch`.
+
+### 1.10 Appointment Validation Processors (Doc 07)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `appointment-validation:dispatch` processor -- batch call dispatch | 07 Section 6 | **P1** |
+| `appointment-validation:sync` processor -- background status sync | 07 Section 6 | **P1** |
+
+**Status in code:** Both processors are stubs with TODO comments.
+
+### 1.11 Billing Processors (Doc 11)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `billing:snapshot` processor -- daily snapshot of expired periods | 11 "Period Lifecycle" | **P1** |
+| `billing:alerts` processor -- daily usage threshold checks + SMS alerts | 11 "Billing Alert Check" | **P1** |
+
+**Status in code:** Queues registered in QueueModule but no processor files exist.
+
+### 1.12 Infrastructure Processors (Doc 16)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `inbound-call:schedule-sync` processor -- sync phone schedules with ElevenLabs | 08 Section 1.2, 16 Section 2.5 | **P1** |
+| `log:cleanup` processor -- delete old logs past retention | 13 "Log Cleanup" | **P2** |
+| `appointment:reminder` processor -- send reminders via Meta template messages | 16 Section 4.3 | **P0** |
+| `webhook:outgoing` processor -- deliver tenant outgoing webhooks with HMAC + retry | 16 Section 5.4 | **P1** |
+
+**Status in code:** Queues registered but no processor files exist.
+
+### 1.13 Missing Phone Number Endpoints (Doc 03)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `POST /phone-numbers/:id/connect-whatsapp` | 03 Section 3 "API Endpoints" | **P0** |
+| `POST /phone-numbers/:id/disconnect-whatsapp` | 03 Section 3 "API Endpoints" | **P1** |
+| `GET /phone-numbers/:id/whatsapp-status` | 03 Section 3 "API Endpoints" | **P1** |
+| `POST /phone-numbers/:id/toggle-agent` (manual assign/unassign ElevenLabs agent) | 03 Section 3, 08 Section 1.2 | **P1** |
+
+### 1.14 Missing Meta Business API Endpoints (Doc 14)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `POST /whatsapp/meta/connect` -- store WABA ID, phone number ID, encrypted token | 14 Section 9 | **P0** |
+| `GET /whatsapp/meta/status` -- connection status | 14 Section 9 | **P1** |
+| `POST /whatsapp/meta/disconnect` -- clear tokens | 14 Section 9 | **P1** |
+| `POST /whatsapp/instagram/connect` -- Instagram account connection | 14 Section 9 | **P1** |
+| `GET /whatsapp/instagram/status` | 14 Section 9 | **P2** |
+| `POST /whatsapp/instagram/disconnect` | 14 Section 9 | **P2** |
+
+### 1.15 Missing Patient Endpoints (Doc 19, 21)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| Patient documents CRUD (`GET/POST/DELETE /patients/:id/documents`) | 19 Section 4 | **P1** |
+| Patient photo sets CRUD (`GET/POST/PUT/DELETE /patients/:id/photo-sets`) | 21 Section 7 | **P1** |
+| Patient photo upload (`POST /patients/:id/photo-sets/:setId/photos`) | 21 Section 5 | **P1** |
+| Patient merge/duplicate resolution (`POST /patients/merge`) | 19 Section 10 | **P2** |
+| Patient timeline aggregation (`GET /patients/:id/timeline`) | 19 Section 6 | **P2** |
+| Examination records CRUD (`GET/POST/PUT/DELETE /patients/:id/examinations`) | 19 "Examination Records" | **P1** |
+
+**Status in code:** `patients.controller.ts` has CRUD, search, medical history, and notes. No document, photo-set, examination, or timeline endpoints exist. Service files `documents.service.ts`, `photo-sets.service.ts`, `examinations.service.ts` exist but their implementations need verification.
+
+### 1.16 Missing Audit Log Endpoint (Doc 13)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| `GET /platform/audit-logs` -- cross-tenant audit trail for superadmin/sales | 13 "Audit Log Endpoints" | **P2** |
+
+### 1.17 Forgot Password Email Sending (Doc 02)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| Actual email sending in `forgotPassword()` | 02 Section 8 | **P1** |
+
+**Status in code:** `auth.service.ts` line 302: `// TODO: Send email with rawToken (not hashed) in the reset link`. Token is generated and hashed but never sent.
+
+### 1.18 Meta Webhook Message Processing Pipeline (Doc 04, 14)
+
+| Gap | Doc Reference | Priority |
+|-----|--------------|----------|
+| Full message processing pipeline after Meta webhook fires event (`meta.whatsapp.message`) | 04 Section 2 (Steps 1-12), 14 Section 4.2 | **P0** |
+| Webhook payload normalization from Meta format to internal format | 14 Section 2.7 | **P0** |
+| Instagram DM message processing (similar pipeline for `meta.instagram.message`) | 14 Section 3.2 | **P1** |
+
+**Status in code:** `meta-webhook.controller.ts` correctly verifies HMAC, extracts messages, and emits events. But no `@OnEvent('meta.whatsapp.message')` listener exists in the WhatsApp module to process the emitted events.
+
+---
+
+## 2. Implemented Features NOT Documented
+
+| Feature | Location | Notes |
+|---------|----------|-------|
+| `GET /appointments` -- paginated list with filters | `appointments/appointments.controller.ts` | Appointments CRUD endpoints exist but are not listed in IMPLEMENTATION_STATUS.md |
+| `GET /appointments/stats` | `appointments/appointments.controller.ts` | Same -- missing from status doc |
+| `POST /appointments` | `appointments/appointments.controller.ts` | Same |
+| `PUT /appointments/:id` | `appointments/appointments.controller.ts` | Same |
+| `PUT /appointments/:id/status` | `appointments/appointments.controller.ts` | Same |
+| `DELETE /appointments/:id` | `appointments/appointments.controller.ts` | Same |
+| `GET /appointments/:id` | `appointments/appointments.controller.ts` | Same |
+| `AppointmentsModule` | `src/appointments/` | Entire module not listed in IMPLEMENTATION_STATUS endpoints section |
+| `DoctorProfilesService` | `src/users/doctor-profiles.service.ts` | Doctor profile management exists in code but not documented in architecture docs |
+| `PUT /users/:id/doctor-profile` | `src/users/users.controller.ts` | Doctor profile update endpoint exists but not in architecture endpoint tables |
+| `ClinicMetaConnection` management endpoints in `ClinicsModule` | `src/clinics/clinics.controller.ts` | Meta connection CRUD within clinics -- not clearly documented |
+
+---
+
+## 3. Schema Mismatches
+
+### 3.1 ClinicCalendarConnection -- Missing Field
+
+| Field | In Doc | In Prisma | Issue |
+|-------|--------|-----------|-------|
+| `calcn_timezone` | Doc 03 Section 4.1, Doc 07 Section 1.1 -- `String @default("Europe/Istanbul")` | **MISSING** from `schema.prisma` | P0 -- timezone needed for all calendar calculations |
+
+### 3.2 Plan Model -- Missing Enum
+
+| Field | In Doc | In Prisma | Issue |
+|-------|--------|-----------|-------|
+| `plan_language_support` | Doc 11 -- `LanguageSupport @default(single)` enum with `single`, `dual`, `multi` | **MISSING** from schema | P2 -- enum `LanguageSupport` not defined, field not on Plan model |
+
+### 3.3 ClinicMetaConnection -- Doc vs Schema Divergence
+
+| Aspect | Doc 03 (original design) | Doc 14 (updated design) | Prisma Schema | Notes |
+|--------|-------------------------|------------------------|---------------|-------|
+| `meta_type` | Not present | `String` (whatsapp/instagram) | Present | Schema follows Doc 14 |
+| `meta_label` | Not present | `String?` | Present as `@default("")` | OK |
+| `meta_is_active` | Not present | `Boolean @default(true)` | Present | OK |
+| `meta_instagram_connected` | `Boolean @default(false)` | Removed in Doc 14 | Absent | Correct |
+| `meta_encrypted_page_token` | Present (separate from access token) | Merged into `meta_encrypted_access_token` | Absent | Correct per Doc 14 |
+
+Doc 03 and Doc 14 show different schemas for `ClinicMetaConnection`. The Prisma schema follows Doc 14 (newer). This is correct but Doc 03 should be updated for consistency.
+
+### 3.4 Naming Convention Drift in Database Schema Doc
+
+| Table | Doc 01 prefix | Actual Prisma prefix | Issue |
+|-------|--------------|---------------------|-------|
+| `treatment_plans` | `tplan_` | `plan_` | Prisma uses `plan_` prefix which collides with the `plans` table convention |
+
+The Prisma schema uses `plan_` prefix for both `plans` and `treatment_plans`, which matches what is in code but differs from the `tplan_` convention in Doc 01.
+
+### 3.5 Missing Tables in Prisma (Present in Doc 01)
+
+| Table | Doc Reference | In Prisma | Notes |
+|-------|--------------|-----------|-------|
+| `tasks` | Doc 19 -- Patient has `tasks Task[]` relation | **MISSING** | No Task model in schema. Patient model shows a `tasks` relation in doc but not in code |
+
+### 3.6 Present in Prisma but NOT in Architecture Docs
+
+| Model | In Prisma | In Docs | Notes |
+|-------|-----------|---------|-------|
+| `Transcription` | Yes (full model) | Doc 01 mentions it | Legacy carry-over; not referenced by any architecture doc beyond the schema list |
+| `Summary` | Yes (full model) | Doc 01 mentions it | Same as above |
+| `Migration` | Yes (full model) | Doc 01 mentions it | Schema migration tracking -- infrastructure |
+
+---
+
+## 4. Configuration Gaps
+
+### 4.1 Missing Environment Variables
+
+| Env Variable | Described In | In `.env` | Status |
+|-------------|-------------|-----------|--------|
+| `TEKTIPPAY_ENCRYPTION_KEY` | Doc 12 "Six AES-256-GCM Encryption Keys" | Missing | **STUB** -- TekTipPay deferred |
+| `GOOGLE_OAUTH_STATE_SECRET` | Doc 07 Section 1.2 | Present but empty | **P0** -- needed for Google Calendar OAuth CSRF protection |
+
+### 4.2 Modules Described as Global but Missing @Global
+
+All infrastructure modules that should be `@Global()` are correctly annotated: `ConfigModule`, `DatabaseModule`, `RedisModule`, `QueueModule`, `EncryptionModule`, `AuthModule`, `AuditModule`, `LoggingModule`, `AIModule`, `MinioModule`. No gap here.
+
+Modules NOT marked `@Global()` that doc 00 suggests should be importable everywhere:
+- `ElevenLabsModule` -- not `@Global()`, but used by many modules. Currently imported individually where needed, which is fine.
+- `MetaBusinessModule` -- same pattern, not `@Global()`, imported where needed. Acceptable.
+
+### 4.3 Missing Package Dependencies
+
+| Package | Required For | In `package.json` | Status |
+|---------|-------------|-------------------|--------|
+| `sharp` | Thumbnail generation for patient photos (Doc 21 Section 3.3) | **MISSING** | P1 -- needed for photo upload |
+| `@anthropic-ai/sdk` | Anthropic AI provider (Doc 15) | Present | OK |
+| `openai` | OpenAI AI provider (Doc 15) | Present | OK |
+| `@nestjs/platform-socket.io` | WebSocket gateway (Doc 17) | Present | OK (but unused) |
+| `@socket.io/redis-adapter` | Multi-instance WS support (Doc 17) | Present | OK (but unused) |
+
+---
+
+## 5. Security Gaps
+
+### 5.1 Tenant-Scoping Middleware NOT Implemented
+
+- **Doc 00 Rule 1, Doc 12:** "Every DB query is tenant-scoped. Enforced at the Prisma middleware layer."
+- **Actual:** No Prisma `$use()` middleware exists. Each service manually adds `tenantId` to WHERE clauses. This is the single highest-risk security gap -- a developer forgetting `tenantId` in a query would leak cross-tenant data.
+- **Priority: P0**
+
+### 5.2 Webhook HMAC Verification -- Partial
+
+| Webhook | Doc Requirement | Implementation | Status |
+|---------|----------------|----------------|--------|
+| Meta Business (`POST /webhooks/meta`) | HMAC-SHA256 with `META_APP_SECRET` | **Implemented** in `meta-webhook.controller.ts` | OK |
+| ElevenLabs post-call (`POST /webhooks/elevenlabs`) | HMAC or API key verification | Enqueues to BullMQ but no signature verification visible | **P1** |
+| ElevenLabs tools (`POST /webhooks/elevenlabs/tools/:toolName`) | `x-api-key` header check | Checks `x-api-key` against `ELEVENLABS_WEBHOOK_SECRET` | OK |
+
+### 5.3 Rate Limiting -- Partially Applied
+
+| Route | Doc Requirement | Implementation | Status |
+|-------|----------------|----------------|--------|
+| `POST /auth/login` | 5/min per IP | Global ThrottlerModule is 200/min. Doc-specific rate not applied | **P1** |
+| `POST /auth/forgot-password` | 3/15min per email | Not specifically rate-limited | **P1** |
+| `POST /auth/register` | 3/hr per IP | Not specifically rate-limited | **P1** |
+| `/webhooks/*` | 100/min per IP | Not specifically rate-limited | **P1** |
+
+Global rate limit is set (200/min in `app.module.ts`) but per-route overrides described in Doc 12 Section "Rate Limiting Details" are not applied.
+
+### 5.4 Message Encryption at Rest
+
+- **Doc 04, 12:** `msg_text` and `msg_quoted_text` encrypted with AES-256-GCM using `MESSAGE_ENCRYPTION_KEY`.
+- **Actual:** `MESSAGE_ENCRYPTION_KEY` is in `.env` and `EncryptionService` is implemented. WhatsApp service uses it for message storage/retrieval.
+- **Status: OK** -- Implemented per IMPLEMENTATION_STATUS.md.
+
+### 5.5 Patient PII Encryption
+
+- **Doc 12:** TC Kimlik, medical history, exam records, clinical notes encrypted with `PATIENT_PII_ENCRYPTION_KEY`.
+- **Actual:** Encryption key present. PatientsService uses it.
+- **Status: OK** -- Implemented.
+
+### 5.6 Opaque Token Authentication
+
+- **Doc 02:** Client never sees JWT. Opaque tokens map to JWTs in Redis.
+- **Actual:** Fully implemented.
+- **Status: OK**
+
+---
+
+## 6. Integration Gaps
+
+### 6.1 Meta Business API (`meta-whatsapp.service.ts`)
+
+| Feature | Doc Reference | Implemented | Priority |
+|---------|--------------|-------------|----------|
+| `sendMessage()` (text) | 14 Section 2.1 | Yes | OK |
+| `sendTemplate()` (template messages) | 14 Section 2.2 | Yes | OK |
+| `sendMedia()` (image/video/audio/document) | 14 Section 2.3 | Yes | OK |
+| `sendInteractive()` (buttons/lists) | 14 Section 2.4 | Yes | OK |
+| `downloadMedia()` (get media from Meta CDN) | 14 Section 5.2 | Needs verification | **P0** |
+| Instagram DM sending | 14 Section 3.1 | `meta-instagram.service.ts` exists | Needs verification |
+
+### 6.2 ElevenLabs (`elevenlabs.service.ts`)
+
+| Feature | Doc Reference | Implemented | Priority |
+|---------|--------------|-------------|----------|
+| `getSignedUrl()` for WS connection | 04 Section 10 | Yes | OK |
+| `getConversation()` for cost/status | 04 Section 12 | Yes | OK |
+| `getBatchCall()` for validation sync | 07 Section 6 | Yes | OK |
+| `submitBatchCall()` | 07 Section 6 | Yes | OK |
+| `sipTrunkOutboundCall()` | 08 Section 2.1 | Yes | OK |
+| STT via Scribe API | 04 Section 2 Step 3 | Yes | OK |
+| WebSocket text-only chat integration | 04 Section 4 | **NOT IMPLEMENTED** -- this is the actual WS client code that lives in `whatsapp-agent.service.ts`, not `elevenlabs.service.ts` | **P0** |
+
+### 6.3 Google Calendar (`google-calendar.service.ts`)
+
+| Feature | Doc Reference | Implemented | Priority |
+|---------|--------------|-------------|----------|
+| OAuth2 flow (auth URL generation) | 07 Section 1.2 | Yes | OK |
+| OAuth callback (code exchange, token encryption, storage) | 07 Section 1.2 | Yes | OK |
+| Token caching in Redis with mutex | 07 Section 1.3 | Yes | OK |
+| FreeBusy API for availability checking | 07 Section 2 | Yes | OK |
+| Event creation (appointment booking) | 07 Section 3 | Yes | OK |
+| Event deletion (appointment cancellation) | 07 Section 4 | Yes | OK |
+| Disconnect flow (revoke token, clear Redis) | 07 Section 1.4 | Yes | OK |
+| Calendar listing for selection | 07 related | Yes | OK |
+
+### 6.4 MinIO (`minio.service.ts`)
+
+| Feature | Doc Reference | Implemented | Priority |
+|---------|--------------|-------------|----------|
+| `putObject()` | 18 Section 6 | Yes | OK |
+| `presignedGetObject()` | 18 Section 6 | Yes | OK |
+| `removeObject()` / `removeObjects()` | 18 Section 6 | Yes | OK |
+| `getObject()` | 18 Section 6 | Yes | OK |
+| `objectExists()` | 18 Section 6 | Yes | OK |
+| Bucket auto-creation on startup | 18 Section 6 | Yes | OK |
+
+---
+
+## 7. Priority Classification Summary
+
+### P0 -- Blocks Launch (22 items)
+
+1. WhatsApp AI engine: ElevenLabs WS connection, message send/receive, tool call handling
+2. Grace period BullMQ processor (activates AI after waiting)
+3. Message buffer BullMQ processor (debounce + send to AI)
+4. Session cleanup sweep (2h inactivity auto-resolve)
+5. Dynamic variables for ElevenLabs (`user_summary`, `current_date`)
+6. Message deduplication on echo
+7. System message filtering (40+ regex patterns)
+8. Patient find-or-create on first contact
+9. Self-sent message handling
+10. Redis WS connection state management
+11. Operator `forwardToOperator()` with REF code and media forwarding
+12. Operator `handleOperatorReply()` with response injection
+13. REF code generation
+14. All 5 calendar tool handlers (check, reserve, list, cancel, reschedule)
+15. `forward_to_operator` tool handler
+16. WebSocket gateway (`EventsGateway`) for real-time dashboard
+17. 11 WS event types for live updates
+18. Prisma tenant-scoping middleware (auto-inject WHERE tenantId)
+19. ElevenLabs post-call webhook processor (Call + CallDetail + summary + billing)
+20. Meta webhook message processing pipeline (event listener + full pipeline)
+21. `POST /phone-numbers/:id/connect-whatsapp`
+22. `POST /whatsapp/meta/connect` (Meta Business setup)
+
+### P1 -- Important, Before Launch (28 items)
+
+1. Chat continuity (`continuation_directive` builder)
+2. AI shift scheduling check
+3. Session recovery on startup
+4. Voice transcription (STT pipeline)
+5. Fixed first message on new session
+6. Cost sweep processor
+7. Profile update processor (AI summary)
+8. Session labels processor (sentiment + categories)
+9. Message cleanup processor (retention enforcement)
+10. Operator expiry processor
+11. Forward conversation to operator (text-only)
+12. Send example photo tool
+13. `check_patient_history` tool handler
+14. `call_patient` tool handler
+15. `confirm_appointment_validation` tool handler
+16. ElevenLabs tools webhook processor
+17. Outbound campaign dispatch + sync processors
+18. Appointment validation dispatch + sync processors
+19. Billing snapshot + alert processors
+20. Inbound call schedule-sync processor
+21. Appointment reminder processor
+22. Webhook outgoing processor
+23. Per-route rate limiting (login, register, forgot-password, webhooks)
+24. ElevenLabs post-call webhook HMAC verification
+25. Request context interceptor (AsyncLocalStorage + correlation IDs)
+26. HTTP exception filter
+27. Patient documents CRUD
+28. Patient photo sets / photos CRUD + `sharp` dependency
+29. Examination records CRUD
+30. Forgot password email sending
+31. Phone number disconnect-whatsapp, whatsapp-status, toggle-agent endpoints
+32. Meta connect/disconnect/status endpoints
+
+### P2 -- Nice to Have (7 items)
+
+1. Typing indicator handler in WS gateway
+2. Log cleanup processor
+3. Patient merge/duplicate resolution
+4. Patient timeline aggregation
+5. Instagram connect/disconnect/status endpoints
+6. Cross-tenant audit trail endpoint (`/platform/audit-logs`)
+7. `LanguageSupport` enum on Plan model
+
+### STUB -- Intentionally Deferred (4 items)
+
+1. NetGSM SMS integration (stub module, returns `{ success: false }`)
+2. TekTipPay payment integration (stub module, returns `{ success: false }`)
+3. `request_payment` tool handler (returns "not yet available")
+4. `send_sms` tool handler (returns "not yet available")
+
+---
+
+## 8. Recommendations
+
+1. **Tenant-scoping middleware is the highest-risk item.** Every query without it is a potential cross-tenant data leak. Implement this first.
+2. **WhatsApp AI engine is the highest-effort item.** The ElevenLabs WS integration, message pipeline, and all 8 BullMQ processors form a single interconnected unit. Plan for this as one concentrated sprint.
+3. **WebSocket gateway should be implemented alongside WhatsApp engine** since both emit/consume the same events.
+4. **Tool handlers can be implemented incrementally** -- calendar tools first (most used by patients), then operator tools, then the rest.
+5. **The `calcn_timezone` field is missing from Prisma schema** -- add it before any calendar-related work proceeds.
+6. **Update Doc 03** to match Doc 14's ClinicMetaConnection design (the code already follows Doc 14).
+7. **Add `sharp` to `package.json`** before implementing patient photo uploads.