elevenlabs-webhook-nodejs 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,173 @@
+export interface ServerConfig {
+    port: number;
+    env: string;
+}
+export interface MongoDBConfig {
+    uri: string;
+}
+export interface ElevenLabsConfig {
+    apiKey: string;
+    webhookSecret: string;
+    defaultProfileAgentId: string;
+}
+export interface AIProviderConfig {
+    apiKey: string;
+    model: string;
+}
+export interface AIConfig {
+    provider: 'openai' | 'gemini';
+    summaryLanguage: string;
+    summaryMaxTokens: number;
+    openai: AIProviderConfig;
+    gemini: AIProviderConfig;
+}
+export interface UnipileConfig {
+    apiKey: string;
+    dsn: string;
+    webhookSecret: string;
+}
+export interface TwilioConfig {
+    accountSid: string;
+    authToken: string;
+    whatsappNumber: string;
+}
+export interface JWTConfig {
+    accessSecret: string;
+    refreshSecret: string;
+    accessExpiry: string;
+    refreshExpiry: string;
+}
+export interface AdminConfig {
+    password: string;
+}
+export interface LoggingConfig {
+    level: string;
+}
+export interface GoogleCalendarConfig {
+    clientId: string;
+    clientSecret: string;
+    callbackUrl: string;
+    tokenEncryptionKey: string;
+    oauthStateSecret: string;
+    frontendUrl: string;
+}
+export interface NetGsmConfig {
+    username: string;
+    password: string;
+    msgheader: string;
+    apiUrl: string;
+}
+export interface AppConfig {
+    server: ServerConfig;
+    mongodb: MongoDBConfig;
+    elevenlabs: ElevenLabsConfig;
+    ai: AIConfig;
+    unipile: UnipileConfig;
+    baileys: UnipileConfig;
+    twilio: TwilioConfig;
+    jwt: JWTConfig;
+    admin: AdminConfig;
+    logging: LoggingConfig;
+    google: GoogleCalendarConfig;
+    netgsm: NetGsmConfig;
+}
+export interface TranscriptEntry {
+    role: string;
+    message: string;
+    time_in_call_secs?: number;
+    tool_calls?: unknown[];
+    tool_results?: unknown[];
+    interrupted?: boolean;
+    source_medium?: string;
+}
+export interface PhoneCallInfo {
+    external_number?: string;
+    [key: string]: unknown;
+}
+export interface CallMetadata {
+    start_time_unix_secs?: number;
+    call_duration_secs?: number;
+    cost?: number;
+    termination_reason?: string;
+    main_language?: string;
+    phone_call?: PhoneCallInfo;
+}
+export interface WebhookPayloadData {
+    conversation_id: string;
+    agent_id: string;
+    agent_name?: string;
+    user_id?: string;
+    status: string;
+    transcript: TranscriptEntry[];
+    metadata?: CallMetadata;
+    analysis?: Record<string, unknown>;
+}
+export interface ElevenLabsWebhookPayload {
+    type: string;
+    event_timestamp: number;
+    data: WebhookPayloadData;
+}
+export interface AISummaryResult {
+    summary: string;
+    tokenUsage: {
+        prompt_tokens: number | null;
+        completion_tokens: number | null;
+        total_tokens: number | null;
+    };
+    model: string;
+}
+export interface AISummaryOptions {
+    language?: string;
+    agentId?: string;
+    maxTokens?: number;
+    summaryPrompt?: string;
+    systemMessage?: string;
+}
+export interface MessageTemplate {
+    headerPrefix: string;
+}
+export interface AgentPromptConfig {
+    name?: string;
+    summaryPrompt: string | null;
+    systemMessage: string | null;
+    messageTemplate: MessageTemplate;
+}
+export interface AgentPromptsConfig {
+    agents: Record<string, AgentPromptConfig>;
+    default: AgentPromptConfig;
+}
+export interface TemplateVariables {
+    caller_number: string;
+    call_summary: string;
+}
+export interface NotificationResult {
+    recipient_id: string;
+    recipient_name: string;
+    recipient_type: 'group' | 'contact';
+    sent_at?: Date;
+    message_sid?: string;
+    error?: string;
+}
+import { UserRole } from '../modules/auth/auth.model';
+import { Feature } from '../modules/tenants/tenant.model';
+export interface JWTAccessPayload {
+    id: string;
+    tenant_id: string;
+    role: UserRole;
+    enabled_features: Feature[];
+}
+export interface JWTRefreshPayload {
+    id: string;
+    type: 'refresh';
+}
+declare module 'fastify' {
+    interface FastifyInstance {
+        authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    }
+}
+declare module '@fastify/jwt' {
+    interface FastifyJWT {
+        payload: JWTAccessPayload;
+        user: JWTAccessPayload;
+    }
+}

package/dist/types/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":""}

package/dist/utils/logger.d.ts

@@ -0,0 +1,3 @@
+import winston from 'winston';
+declare const logger: winston.Logger;
+export default logger;

package/dist/utils/logger.js

@@ -0,0 +1,105 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const winston_1 = __importDefault(require("winston"));
+const winston_transport_1 = __importDefault(require("winston-transport"));
+// Buffered MongoDB transport — writes logs in batches to avoid per-log DB overhead
+class MongoTransport extends winston_transport_1.default {
+    buffer = [];
+    flushInterval = null;
+    LogModel = null;
+    ready = false;
+    constructor(opts) {
+        super(opts);
+        // Lazy-load model to avoid circular deps and early mongoose access
+        this.flushInterval = setInterval(() => this.flush(), 5000);
+    }
+    async getModel() {
+        if (!this.LogModel) {
+            const mod = await Promise.resolve().then(() => __importStar(require('../modules/logs/log.model')));
+            this.LogModel = mod.default;
+            this.ready = true;
+        }
+        return this.LogModel;
+    }
+    log(info, callback) {
+        const { level, message, timestamp, service, ...rest } = info;
+        this.buffer.push({
+            level,
+            message,
+            meta: rest,
+            service: service || 'elevenlabs-webhook',
+            timestamp: timestamp ? new Date(timestamp) : new Date(),
+        });
+        // Flush if buffer gets large
+        if (this.buffer.length >= 50) {
+            this.flush();
+        }
+        callback();
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer.splice(0, this.buffer.length);
+        try {
+            const Model = await this.getModel();
+            await Model.insertMany(batch, { ordered: false });
+        }
+        catch {
+            // Silently drop — can't log about logging failures
+        }
+    }
+    async close() {
+        if (this.flushInterval)
+            clearInterval(this.flushInterval);
+        await this.flush();
+    }
+}
+const logger = winston_1.default.createLogger({
+    level: process.env.LOG_LEVEL || 'info',
+    format: winston_1.default.format.combine(winston_1.default.format.timestamp(), winston_1.default.format.errors({ stack: true }), winston_1.default.format.json()),
+    defaultMeta: { service: 'elevenlabs-webhook' },
+    transports: [
+        new winston_1.default.transports.Console({
+            format: winston_1.default.format.combine(winston_1.default.format.colorize(), winston_1.default.format.simple())
+        }),
+        new MongoTransport(),
+    ]
+});
+exports.default = logger;
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,sDAA8B;AAC9B,0EAA0C;AAE1C,mFAAmF;AACnF,MAAM,cAAe,SAAQ,2BAAS;IAC5B,MAAM,GAA+G,EAAE,CAAC;IACxH,aAAa,GAA0C,IAAI,CAAC;IAC5D,QAAQ,GAA8D,IAAI,CAAC;IAC3E,KAAK,GAAG,KAAK,CAAC;IAEtB,YAAY,IAAuC;QACjD,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,mEAAmE;QACnE,IAAI,CAAC,aAAa,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7D,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,GAAG,GAAG,wDAAa,2BAA2B,GAAC,CAAC;YACtD,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC;YAC5B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,GAAG,CAAC,IAAsG,EAAE,QAAoB;QAC9H,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QAE7D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,KAAK;YACL,OAAO;YACP,IAAI,EAAE,IAA+B;YACrC,OAAO,EAAG,OAAkB,IAAI,oBAAoB;YACpD,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAmB,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE;SAClE,CAAC,CAAC;QAEH,6BAA6B;QAC7B,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;YAC7B,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;QAED,QAAQ,EAAE,CAAC;IACb,CAAC;IAEO,KAAK,CAAC,KAAK;QACjB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAErC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAExD,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,MAAM,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;QACrD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,aAAa;YAAE,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC1D,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF;AAED,MAAM,MAAM,GAAG,iBAAO,CAAC,YAAY,CAAC;IAClC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;IACtC,MAAM,EAAE,iBAAO,CAAC,MAAM,CAAC,OAAO,CAC5B,iBAAO,CAAC,MAAM,CAAC,SAAS,EAAE,EAC1B,iBAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EACtC,iBAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CACtB;IACD,WAAW,EAAE,EAAE,OAAO,EAAE,oBAAoB,EAAE;IAC9C,UAAU,EAAE;QACV,IAAI,iBAAO,CAAC,UAAU,CAAC,OAAO,CAAC;YAC7B,MAAM,EAAE,iBAAO,CAAC,MAAM,CAAC,OAAO,CAC5B,iBAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,EACzB,iBAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CACxB;SACF,CAAC;QACF,IAAI,cAAc,EAAE;KACrB;CACF,CAAC,CAAC;AAEH,kBAAe,MAAM,CAAC"}

package/docker-compose.nestjs.yml

@@ -0,0 +1,89 @@
+services:
+  # ─── PostgreSQL ─────────────────────────────────────────
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: portal_asistan
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    volumes:
+      - nestjs_pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    networks:
+      - nestjs-net
+    # No ports — internal only
+
+  # ─── Redis ──────────────────────────────────────────────
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    networks:
+      - nestjs-net
+
+  # ─── MinIO (S3-compatible storage) ─────────────────────
+  minio:
+    image: minio/minio:latest
+    restart: unless-stopped
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    volumes:
+      - nestjs_miniodata:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - nestjs-net
+
+  # ─── NestJS Backend ─────────────────────────────────────
+  backend:
+    build:
+      context: ./nestjs
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+    env_file:
+      - ./nestjs/.env.docker
+    networks:
+      - nestjs-net
+    # No ports — only accessible via nginx proxy
+
+  # ─── Frontend (nginx serves static + proxies /api) ──────
+  frontend:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    depends_on:
+      - backend
+    ports:
+      - "127.0.0.1:3021:80"
+    networks:
+      - nestjs-net
+
+networks:
+  nestjs-net:
+    driver: bridge
+
+volumes:
+  nestjs_pgdata:
+  nestjs_miniodata:

package/docker-compose.yml

@@ -0,0 +1,78 @@
+services:
+  api:
+    build: .
+    ports:
+      - "127.0.0.1:3010:3000"
+    env_file:
+      - .env
+    environment:
+      PORT: 3000
+      MONGODB_URI: mongodb://${MONGO_USER:-admin}:${MONGO_PASS:-changeme}@mongo:27017/asistan724?authSource=admin
+      BAILEYS_DSN: http://baileys:3001
+      BAILEYS_API_KEY: ${BAILEYS_API_KEY:-}
+    depends_on:
+      mongo:
+        condition: service_healthy
+    networks:
+      - asistan724-net
+    restart: unless-stopped
+
+  baileys:
+    build: ./baileys
+    environment:
+      PORT: 3001
+      BAILEYS_API_KEY: ${BAILEYS_API_KEY:?BAILEYS_API_KEY is required}
+      MONGODB_URI: mongodb://${MONGO_USER:-admin}:${MONGO_PASS:-changeme}@mongo:27017/asistan724?authSource=admin
+      WEBHOOK_AUTO_URL: http://api:3000/webhooks/unipile
+      WEBHOOK_AUTO_SECRET: ${BAILEYS_WEBHOOK_SECRET:-}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+      MEDIA_FORWARD_TO: ${MEDIA_FORWARD_TO:-}
+    depends_on:
+      mongo:
+        condition: service_healthy
+    networks:
+      - asistan724-net
+    restart: unless-stopped
+
+  mongo:
+    image: mongo:7
+    ulimits:
+      nofile:
+        soft: 64000
+        hard: 64000
+    ports:
+      - "127.0.0.1:27017:27017"
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: ${MONGO_USER:-admin}
+      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASS:-changeme}
+    volumes:
+      - mongo_data:/data/db
+    healthcheck:
+      test: mongosh --eval "db.runCommand('ping').ok" --quiet
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    deploy:
+      resources:
+        limits:
+          memory: 4g
+    networks:
+      - asistan724-net
+    restart: unless-stopped
+
+  web:
+    build: ./web
+    ports:
+      - "127.0.0.1:3020:80"
+    depends_on:
+      - api
+    networks:
+      - asistan724-net
+    restart: unless-stopped
+
+networks:
+  asistan724-net:
+    driver: bridge
+
+volumes:
+  mongo_data:

package/docs/AI_AGENT_ENHANCEMENT_PLAN.md

@@ -0,0 +1,164 @@
+# Plan: Making Portal Asistan 7/24 AI Agent Friendly
+
+> Implementation roadmap for transforming the system from reactive AI to proactive AI agent platform.
+> Created: 2026-04-03
+
+## Context
+
+The system is currently **reactive only** — AI responds to patient contact but never initiates. Tools are isolated (no cross-call context), patient profiles are unstructured encrypted text, and the AI has no knowledge base beyond what's hardcoded in ElevenLabs prompts. This plan adds structured intelligence, proactive capabilities, and smarter tools to make the system a true AI agent platform.
+
+---
+
+## Phase 1: Smart Context (Foundation)
+
+### 1A. Structured Patient AI Profile
+- Add `patient_ai_profile Json @default("{}")` to Patient model in Prisma
+- Structure: `{ interests[], preferences{}, lifecycle{ stage, next_recall_due }, risk_signals[], notes[] }`
+- Modify `src/whatsapp/processors/profile-update.processor.ts` — use `AIService.generateJson()` instead of text, write to both `patient_ai_profile` (JSON) and `patient_ai_summary` (encrypted text)
+- Profile is NOT encrypted (no PII — only labels and scores), making it queryable
+
+### 1B. Clinic Knowledge Base
+- New table `clinic_knowledge_entries` (kb_id, clinic_id, category, title, content, tags)
+- New module: `src/knowledge-base/` — service, controller, DTOs
+- New tool: `src/tools/handlers/knowledge.tools.ts` — `query_knowledge_base` tool (text search on clinic entries)
+- Auto-sync method: `syncFromTreatments()` converts treatment catalog to knowledge entries
+- Simple PostgreSQL `ILIKE` search — no vector DB needed (<200 entries per clinic)
+
+### 1C. Rich Patient Context on Inbound
+- New service: `src/patients/patient-context.service.ts`
+- Assembles: patient profile + upcoming appointments + treatment plans + open leads + knowledge summary
+- Replace `buildPatientSummary()` in `whatsapp-agent.service.ts` with rich context
+- Same context used for voice call `dynamic_variables` pre-fetch
+
+### 1D. Enrich ToolContext
+- Add `patientProfile?` and `previousResults?` to `ToolContext` in `src/tools/tool.interfaces.ts`
+- Populate when building context in WhatsApp agent + ElevenLabs HTTP adapter
+- Tools can make decisions based on patient stage, interests, history without re-querying
+
+---
+
+## Phase 2: Proactive AI Engine
+
+### 2A. Trigger Rule System
+- New tables: `proactive_trigger_rules`, `proactive_trigger_executions`
+- New module: `src/proactive/` — rule engine, action service, processors
+- New BullMQ queues: `proactive-trigger`, `proactive-action`
+- Event-driven: listens to existing events (`session.resolved`, `appointment.created`, `lead.new`)
+- Configurable rules per clinic: event → conditions → action (send WhatsApp, schedule call, create task)
+- Cooldown enforcement: won't contact same patient for same reason within N hours
+
+### 2B. Appointment Reminders
+- Implement existing stub `appointment-reminder` processor
+- Add `appt_reminder_sent_24h`, `appt_reminder_sent_2h` booleans to Appointment
+- AI-personalized reminder text via `AIService.generateText()`
+- Send via Meta WhatsApp API
+
+### 2C. Lead Re-engagement
+- Repeatable BullMQ job scans stale leads (new_lead + no activity > X days)
+- Emits `lead.stale` event → trigger engine evaluates → sends personalized outreach
+
+### 2D. Recall Automation
+- Repeatable BullMQ job scans completed treatment plan items where completion + `treatment_recall_days` has passed
+- Emits `recall.due` event → trigger engine sends recall reminder
+
+---
+
+## Phase 3: Intelligent Tools
+
+### 3A. Cross-Tool Context
+- `ElevenLabsWsAdapter` maintains per-session result history (last 5 tool results)
+- Injected as `previousResults` in `ToolContext` for next tool call
+- Tools can reference prior results (e.g., `reserve_slot` knows what `check_availability` returned)
+
+### 3B. Error Recovery
+- Extend `ToolDefinition` with `retryable`, `maxRetries`, `fallbackTool`, `errorHints`
+- `ToolRegistryService.execute()` handles retry + fallback automatically
+- Error hints returned to AI for better patient communication
+
+### 3C. Domain Filtering
+- Add `domains[]` to `ToolDefinition` (scheduling, pricing, medical, general)
+- `getAvailableTools()` gains optional domain filter
+- Reduces irrelevant tools in AI context
+
+---
+
+## Phase 4: Analytics & Insights
+
+### 4A. AI-Generated Daily Insights
+- New table: `clinic_daily_insights`
+- New module: `src/analytics/`
+- Daily BullMQ job computes metrics → AIService generates Turkish summary
+- Metrics: conversion rate, sentiment trends, top categories, busiest hours
+
+### 4B. Churn Risk Scoring
+- Computed during profile update (Phase 1A)
+- `risk_score: 0-100` in `patient_ai_profile.lifecycle`
+- Based on: days since contact, sentiment, cancellations, lead status
+
+### 4C. Revenue Attribution
+- Add `appt_attributed_to` to Appointment ("ai_whatsapp", "ai_voice", "human")
+- Set by `reserve_slot` tool or dashboard booking
+- Analytics endpoint aggregates by attribution source
+
+---
+
+## Schema Changes Summary
+
+```
+Patient:          + patient_ai_profile Json
+Appointment:      + appt_reminder_sent_24h Boolean
+                  + appt_reminder_sent_2h Boolean
+                  + appt_attributed_to String?
+New tables:       clinic_knowledge_entries
+                  proactive_trigger_rules
+                  proactive_trigger_executions
+                  clinic_daily_insights
+```
+
+## New Modules
+
+```
+src/knowledge-base/    — Knowledge base CRUD + query_knowledge_base tool
+src/proactive/         — Trigger rules, engine, action execution
+src/analytics/         — Daily insights, revenue attribution
+```
+
+## Key Files to Modify
+
+- `prisma/schema.prisma` — schema changes
+- `src/tools/tool.interfaces.ts` — ToolContext enrichment
+- `src/tools/tool.decorator.ts` — error recovery + domains
+- `src/tools/tool-registry.service.ts` — retry/fallback logic
+- `src/tools/adapters/elevenlabs-ws.adapter.ts` — cross-tool state
+- `src/whatsapp/whatsapp-agent.service.ts` — PatientContextService injection
+- `src/whatsapp/processors/profile-update.processor.ts` — structured JSON output
+- `src/queue/queue.module.ts` — new queues
+- `src/app.module.ts` — new module imports
+
+## Implementation Timeline
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| Phase 1 | Smart Context | Weeks 1-3 |
+| Phase 2 | Proactive Engine | Weeks 3-6 |
+| Phase 3 | Intelligent Tools | Weeks 6-8 |
+| Phase 4 | Analytics | Weeks 8-10 |
+
+## Key Architectural Decisions
+
+1. **No vector database** — PostgreSQL `ILIKE` is sufficient for <200 knowledge entries per clinic
+2. **Proactive engine is event-driven** — reuses existing EventEmitter, not a separate cron system
+3. **Patient AI profile is unencrypted JSON** — no PII, only labels/scores, queryable for analytics
+4. **ElevenLabs remains conversation owner** — proactive messages are one-way via Meta API, not through ElevenLabs
+5. **Cooldown is per-patient-per-rule** — prevents spam, respects blacklist
+6. **Existing @Tool pattern preserved** — new tools follow same decorator + auto-discovery pattern
+
+## Verification
+
+1. `npm run build` — zero errors after each phase
+2. Start app, register a test tenant, create a clinic
+3. Phase 1: Create knowledge entries via API, verify `query_knowledge_base` tool returns results
+4. Phase 1: Trigger a session resolve, verify `patient_ai_profile` JSON is populated
+5. Phase 2: Create a trigger rule, create a stale lead, verify proactive message is sent
+6. Phase 3: Make two sequential tool calls, verify second has `previousResults`
+7. Phase 4: Run daily insights job, verify `clinic_daily_insights` record created