elevenlabs-webhook-nodejs 1.0.0

package/docs/PROJECT_DESCRIPTION.md

@@ -0,0 +1,1038 @@
+# VoiceAI SaaS Platform — Development Roadmap
+
+## Project Overview
+
+A SaaS platform offering AI-powered voice agents over real phone lines (PSTN/GSM). Tenants enable features based on their needs — any tenant can use any combination of capabilities:
+
+* **Inbound Agent:** AI receptionist — answers calls, handles FAQs, books appointments, sends WhatsApp summaries.
+* **Outbound Campaigns:** AI caller — dials number lists, conducts surveys with branching logic, extracts structured responses, provides analytics.
+
+The platform is **feature-driven, not customer-type-driven.** A clinic can enable outbound appointment reminders. A survey company can enable an inbound support line. New use cases (debt collection, appointment reminders, lead qualification) are added as agent templates without architectural changes.
+
+## Tech Stack
+
+| Layer         | Technology                          |
+| ------------- | ----------------------------------- |
+| Frontend      | React + Vite + TypeScript           |
+| Backend       | Node.js + Fastify + TypeScript      |
+| Database      | MongoDB (Atlas) + Mongoose          |
+| Auth          | @fastify/jwt + bcrypt (custom RBAC) |
+| Job Queue     | BullMQ + Redis                      |
+| Cache         | Redis                               |
+| Voice Engine  | ElevenLabs Conversational AI        |
+| Telephony     | Asterisk + NetGSM SIP Trunk         |
+| Notifications | Twilio (WhatsApp)                   |
+| Post-Call LLM | OpenAI / Google Gemini              |
+| Payments      | Param                               |
+
+## Existing Infrastructure (Already Working)
+
+* [X] NetGSM ↔ Asterisk ↔ ElevenLabs voice pipeline
+* [X] ElevenLabs post-call webhook → LLM summarization → Twilio WhatsApp notification
+* [X] Basic Express backend with Mongoose, OpenAI, Gemini, Twilio SDKs
+* [X] Pricing model defined
+
+---
+
+## Architecture Principles
+
+### Feature-Driven Tenancy
+
+Tenants have  **no type field** . Instead, each tenant has an `enabled_features` array that controls what they can access. Features are gated at the route level via middleware.
+
+```
+Available features:
+- inbound_agent          → receive and handle incoming calls
+- outbound_campaigns     → create campaigns and dial number lists
+- survey_builder         → create and manage surveys
+- whatsapp_notifications → post-call WhatsApp summaries
+```
+
+### Agent Templates
+
+Agent behavior is defined by  **templates** , not tenant type. Each template has its own config schema and prompt builder. Adding a new use case = adding a new template.
+
+```
+Current templates:
+- receptionist    → inbound call handling, FAQs, appointment booking
+- survey          → outbound survey conducting with structured Q&A
+- custom          → tenant provides their own prompt (future/advanced)
+```
+
+### Post-Call Processing Strategies
+
+Each agent defines its own post-call processing strategy, independent of tenant type:
+
+```
+Strategies:
+- summarize              → LLM summarizes the call (clinic use case)
+- extract_survey         → LLM extracts structured survey answers
+- summarize_and_extract  → both (future)
+- none                   → no post-processing
+```
+
+---
+
+## Project Structure
+
+```
+src/
+├── app.ts                    # Fastify instance + plugin registration
+├── server.ts                 # Entry point
+├── config/
+│   └── env.ts                # Typed environment variables
+├── plugins/
+│   ├── auth.ts               # JWT verification + RBAC middleware
+│   ├── features.ts           # Feature-gating middleware (requireFeature)
+│   ├── mongo.ts              # Mongoose connection
+│   └── redis.ts              # Redis + BullMQ setup
+├── modules/
+│   ├── auth/
+│   │   ├── auth.model.ts     # User model (email, password_hash, tenant_id, role)
+│   │   ├── auth.routes.ts    # POST /auth/login, /auth/register, /auth/refresh
+│   │   └── auth.service.ts   # JWT generation, password hashing, validation
+│   ├── tenants/
+│   │   ├── tenant.model.ts
+│   │   ├── tenant.routes.ts
+│   │   └── tenant.service.ts
+│   ├── agents/
+│   │   ├── agent.model.ts
+│   │   ├── agent.routes.ts
+│   │   └── agent.service.ts
+│   ├── calls/
+│   │   ├── call.model.ts
+│   │   ├── call.routes.ts
+│   │   └── call.service.ts
+│   ├── surveys/
+│   │   ├── survey.model.ts
+│   │   ├── survey.routes.ts
+│   │   └── survey.service.ts
+│   ├── campaigns/
+│   │   ├── campaign.model.ts
+│   │   ├── campaign.routes.ts
+│   │   ├── campaign.service.ts
+│   │   └── campaign.worker.ts  # BullMQ worker for dialer logic
+│   ├── billing/
+│   │   ├── billing.model.ts
+│   │   ├── billing.routes.ts
+│   │   └── billing.service.ts  # Param integration
+│   └── webhooks/
+│       ├── elevenlabs.routes.ts
+│       └── elevenlabs.service.ts  # Post-call processing pipeline
+├── templates/
+│   ├── index.ts              # Template registry — maps template name → builder
+│   ├── receptionist.ts       # Prompt builder + config schema for receptionist
+│   └── survey.ts             # Prompt builder + config schema for survey agent
+├── utils/
+│   ├── llm.ts                # OpenAI/Gemini wrapper for post-call processing
+│   ├── twilio.ts             # WhatsApp notification helper
+│   ├── prompt-builder.ts     # Dispatches to correct template builder
+│   └── logger.ts             # Winston logger
+└── types/
+    └── index.ts              # Shared TypeScript interfaces
+```
+
+---
+
+## Database Collections (MongoDB)
+
+### tenants
+
+No type field. Features control what the tenant can access.
+
+```typescript
+{
+  _id: ObjectId,
+  name: string,
+  plan: string,
+  enabled_features: string[],   // ["inbound_agent", "whatsapp_notifications"]
+  settings: {
+    kvkk_consent: boolean,
+    notification_recipients: string[],  // phone numbers for WhatsApp
+    default_language: string,           // "tr", "en"
+  },
+  created_at: Date,
+  updated_at: Date
+}
+```
+
+### users
+
+```typescript
+{
+  _id: ObjectId,
+  tenant_id: ObjectId,       // ref → tenants
+  email: string,
+  password_hash: string,
+  role: "admin" | "manager" | "viewer",
+  name: string,
+  created_at: Date
+}
+```
+
+### agents
+
+Agent carries all behavior. Template defines config schema and prompt generation.
+
+```typescript
+{
+  _id: ObjectId,
+  tenant_id: ObjectId,          // ref → tenants
+  phone_number: string,         // NetGSM number assigned
+  elevenlabs_agent_id: string,
+  direction: "inbound" | "outbound" | "both",
+  agent_template: string,       // "receptionist" | "survey" | "custom"
+
+  config: {
+    // Common fields (all templates)
+    voice_id: string,
+    language: string,
+    greeting: string,
+
+    // Template-specific fields (flexible schema per template)
+    template_data: object
+    // For "receptionist":
+    //   {
+    //     business_name: string,
+    //     business_hours: { day: string, open: string, close: string }[],
+    //     transfer_number: string,
+    //     faq_entries: { question: string, answer: string }[],
+    //     services: string[]
+    //   }
+    //
+    // For "survey":
+    //   {
+    //     intro_script: string,
+    //     outro_script: string,
+    //     default_survey_id: ObjectId | null
+    //   }
+    //
+    // For "custom":
+    //   {
+    //     custom_prompt: string
+    //   }
+  },
+
+  post_call_processing: {
+    strategy: "summarize" | "extract_survey" | "summarize_and_extract" | "none",
+    llm_provider: "openai" | "gemini",
+    whatsapp_notify: boolean,
+    notification_template: string  // "call_summary" | "survey_progress" | "custom"
+  },
+
+  is_active: boolean,
+  created_at: Date,
+  updated_at: Date
+}
+```
+
+### surveys
+
+```typescript
+{
+  _id: ObjectId,
+  tenant_id: ObjectId,       // ref → tenants
+  name: string,
+  description: string,
+  questions: [
+    {
+      id: string,            // e.g. "Q1", "Q2"
+      text: string,          // "How would you rate our service from 1 to 5?"
+      type: "open" | "multiple_choice" | "rating" | "yes_no",
+      options: string[],     // for multiple_choice
+      required: boolean,
+      branch_logic: {
+        condition: string,   // e.g. "answer == 'yes'"
+        go_to: string        // question id to jump to
+      } | null
+    }
+  ],
+  status: "draft" | "active" | "archived",
+  created_at: Date,
+  updated_at: Date
+}
+```
+
+### campaigns
+
+```typescript
+{
+  _id: ObjectId,
+  tenant_id: ObjectId,       // ref → tenants
+  survey_id: ObjectId,       // ref → surveys
+  agent_id: ObjectId,        // ref → agents
+  name: string,
+  status: "draft" | "scheduled" | "running" | "paused" | "completed",
+  phone_list: [
+    {
+      number: string,
+      status: "pending" | "completed" | "failed" | "no_answer" | "voicemail",
+      attempts: number,
+      last_attempt_at: Date | null
+    }
+  ],
+  schedule: {
+    start_date: Date,
+    end_date: Date,
+    daily_start_time: string,   // "09:00"
+    daily_end_time: string,     // "18:00"
+    days_of_week: number[],     // [1,2,3,4,5] = weekdays
+    max_concurrent_calls: number,
+    max_retries: number,
+    retry_delay_minutes: number
+  },
+  stats: {
+    total: number,
+    completed: number,
+    failed: number,
+    no_answer: number,
+    voicemail: number,
+    pending: number
+  },
+  created_at: Date,
+  updated_at: Date
+}
+```
+
+### calls
+
+```typescript
+{
+  _id: ObjectId,
+  tenant_id: ObjectId,       // ref → tenants
+  agent_id: ObjectId,        // ref → agents
+  campaign_id: ObjectId | null,  // ref → campaigns (null for inbound)
+  direction: "inbound" | "outbound",
+  caller_number: string,
+  callee_number: string,
+  duration_seconds: number,
+  status: "completed" | "failed" | "no_answer" | "voicemail" | "transferred",
+  transcript: string,
+  llm_summary: string | null,
+  survey_responses: [
+    {
+      question_id: string,
+      question_text: string,
+      answer: string,
+      parsed_value: any       // structured: number for rating, boolean for yes/no, etc.
+    }
+  ] | null,
+  whatsapp_notification_sent: boolean,
+  recording_url: string | null,
+  created_at: Date
+}
+```
+
+### billing_events
+
+```typescript
+{
+  _id: ObjectId,
+  tenant_id: ObjectId,       // ref → tenants
+  type: "call_charge" | "subscription" | "top_up" | "refund",
+  amount: number,
+  currency: "TRY",
+  call_id: ObjectId | null,  // ref → calls
+  param_transaction_id: string | null,
+  description: string,
+  created_at: Date
+}
+```
+
+### Required Indexes
+
+```typescript
+// calls — most queried collection
+calls: { tenant_id: 1, created_at: -1 }
+calls: { campaign_id: 1, status: 1 }
+calls: { tenant_id: 1, direction: 1, created_at: -1 }
+
+// campaigns
+campaigns: { tenant_id: 1, status: 1 }
+
+// billing
+billing_events: { tenant_id: 1, created_at: -1 }
+
+// users
+users: { email: 1 }  // unique
+users: { tenant_id: 1 }
+
+// agents
+agents: { tenant_id: 1 }
+agents: { elevenlabs_agent_id: 1 }  // for webhook lookup
+```
+
+---
+
+## Auth & Permissions (RBAC)
+
+### JWT Flow
+
+1. `POST /auth/login` → validate email + password → return access token (15min) + refresh token (7d)
+2. React stores access token in memory (NOT localStorage)
+3. Every API request includes `Authorization: Bearer <token>`
+4. Fastify `onRequest` hook decodes JWT → attaches `request.user = { id, tenant_id, role, enabled_features }`
+5. Route-level permission check via role middleware + feature middleware
+
+### Role Permissions Matrix
+
+| Permission                 | admin | manager | viewer |
+| -------------------------- | ----- | ------- | ------ |
+| Edit agent config          | ✓    |         |        |
+| View call history          | ✓    | ✓      | ✓     |
+| View/play transcripts      | ✓    | ✓      | ✓     |
+| Create/edit surveys        | ✓    | ✓      |        |
+| Create/manage campaigns    | ✓    | ✓      |        |
+| Start/pause/stop campaigns | ✓    | ✓      |        |
+| Export data                | ✓    | ✓      | ✓     |
+| Invite/manage users        | ✓    |         |        |
+| Manage billing             | ✓    |         |        |
+| Edit notification settings | ✓    | ✓      |        |
+
+### Middleware Stack
+
+Routes are protected by two layers: **role** and  **feature** .
+
+```typescript
+// Role middleware — checks user role
+function requireRole(...roles: string[]) {
+  return (request, reply) => {
+    if (!roles.includes(request.user.role)) {
+      return reply.code(403).send({ error: "Insufficient role" })
+    }
+  }
+}
+
+// Feature middleware — checks tenant features
+function requireFeature(...features: string[]) {
+  return (request, reply) => {
+    const tenantFeatures = request.user.enabled_features
+    if (!features.every(f => tenantFeatures.includes(f))) {
+      return reply.code(403).send({ error: "Feature not available on your plan" })
+    }
+  }
+}
+
+// Usage in routes — combined:
+fastify.get('/surveys', {
+  preHandler: [requireFeature('survey_builder'), requireRole('admin', 'manager', 'viewer')]
+}, handler)
+
+fastify.post('/campaigns', {
+  preHandler: [requireFeature('outbound_campaigns'), requireRole('admin', 'manager')]
+}, handler)
+
+fastify.get('/calls', {
+  preHandler: [requireRole('admin', 'manager', 'viewer')]
+}, handler)
+```
+
+### Super Admin
+
+Separate role for internal team. `role: "superadmin"` bypasses tenant scoping and feature checks. Used for:
+
+* Provisioning new tenants and setting their enabled_features
+* Assigning phone numbers to agents
+* System-wide monitoring
+* Debugging call issues
+
+---
+
+## API Routes
+
+### Auth
+
+```
+POST   /auth/register          # Create first user + tenant (onboarding)
+POST   /auth/login             # Returns JWT access + refresh tokens
+POST   /auth/refresh           # Refresh access token
+POST   /auth/logout            # Invalidate refresh token
+GET    /auth/me                # Current user profile + tenant features
+```
+
+### Tenants
+
+```
+GET    /tenants/me             # Get current tenant details + enabled_features
+PUT    /tenants/me             # Update tenant settings
+```
+
+### Users (tenant-scoped)
+
+```
+GET    /users                  # List users in tenant
+POST   /users/invite           # Invite user to tenant
+PUT    /users/:id              # Update user role
+DELETE /users/:id              # Remove user from tenant
+```
+
+### Agents (tenant-scoped)
+
+```
+GET    /agents                 # List agents for tenant
+GET    /agents/:id             # Get agent details + config
+PUT    /agents/:id/config      # Update agent configuration (template_data + post_call_processing)
+POST   /agents/:id/toggle      # Enable/disable agent
+GET    /agents/templates       # List available agent templates + their config schemas
+```
+
+### Calls (tenant-scoped)
+
+```
+GET    /calls                  # List calls (paginated, filterable by date/direction/status/agent)
+GET    /calls/:id              # Get call details + transcript + summary + survey_responses
+GET    /calls/:id/recording    # Get call recording URL
+GET    /calls/stats            # Aggregated call statistics
+```
+
+### Surveys (tenant-scoped, requires: survey_builder feature)
+
+```
+GET    /surveys                # List surveys
+POST   /surveys                # Create new survey
+GET    /surveys/:id            # Get survey with questions
+PUT    /surveys/:id            # Update survey
+DELETE /surveys/:id            # Delete survey (only if no active campaigns)
+POST   /surveys/:id/duplicate  # Clone a survey
+```
+
+### Campaigns (tenant-scoped, requires: outbound_campaigns feature)
+
+```
+GET    /campaigns                    # List campaigns
+POST   /campaigns                    # Create campaign (survey_id, phone_list, schedule)
+GET    /campaigns/:id                # Get campaign details + stats
+PUT    /campaigns/:id                # Update campaign config
+POST   /campaigns/:id/start          # Start campaign
+POST   /campaigns/:id/pause          # Pause campaign
+POST   /campaigns/:id/resume         # Resume campaign
+POST   /campaigns/:id/stop           # Stop campaign permanently
+GET    /campaigns/:id/results        # Get structured survey responses
+GET    /campaigns/:id/results/export # Export results as CSV/Excel
+POST   /campaigns/:id/phone-list     # Upload/update phone number list
+```
+
+### Billing (tenant-scoped)
+
+```
+GET    /billing/usage           # Current period usage summary
+GET    /billing/history         # Billing event history
+POST   /billing/checkout        # Initiate Param payment
+POST   /billing/webhook         # Param payment confirmation webhook
+```
+
+### Webhooks (internal, no auth — secured by signature verification)
+
+```
+POST   /webhooks/elevenlabs     # ElevenLabs post-call webhook
+POST   /webhooks/param          # Param payment webhook
+```
+
+### Super Admin (superadmin role only)
+
+```
+GET    /admin/tenants                    # List all tenants
+POST   /admin/tenants                    # Create tenant manually
+PUT    /admin/tenants/:id                # Update tenant (plan, enabled_features)
+PUT    /admin/tenants/:id/features       # Toggle features for a tenant
+POST   /admin/agents                     # Provision new agent (assign phone number to tenant)
+GET    /admin/system/health              # System health (active calls, queue depth, errors)
+GET    /admin/system/usage               # Global usage statistics
+GET    /admin/templates                  # List all agent templates
+```
+
+---
+
+## React Dashboard Pages
+
+### Navigation Rendering
+
+The sidebar dynamically renders based on `tenant.enabled_features`:
+
+```tsx
+// Always visible
+<NavItem to="/dashboard" />
+<NavItem to="/calls" />
+<NavItem to="/settings" />
+
+// Feature-gated
+{features.includes('survey_builder') && <NavItem to="/surveys" />}
+{features.includes('outbound_campaigns') && <NavItem to="/campaigns" />}
+```
+
+### Core Pages (All Tenants)
+
+```
+/login                         # Login page
+/dashboard                     # Overview — call stats, recent calls, usage summary
+/calls                         # Call history table (filterable, sortable, paginated)
+/calls/:id                     # Call detail — transcript, summary, recording playback
+                               #   If survey responses exist, show structured answers too
+/settings                      # Tenant settings
+/settings/agent                # Agent configuration form
+                               #   Renders different config fields based on agent_template:
+                               #   - receptionist: business hours, FAQ builder, services, transfer number
+                               #   - survey: intro/outro scripts, default survey link
+                               #   - custom: raw prompt editor
+/settings/notifications        # WhatsApp notification preferences (requires: whatsapp_notifications)
+/settings/users                # User management (invite, roles)
+/settings/billing              # Usage, payment history, add funds via Param
+```
+
+### Feature-Gated Pages
+
+```
+/surveys                       # Survey list (requires: survey_builder)
+/surveys/new                   # Survey builder — questions, types, branching
+/surveys/:id/edit              # Edit survey
+
+/campaigns                     # Campaign list with status badges (requires: outbound_campaigns)
+/campaigns/new                 # Create campaign — select survey → upload numbers → set schedule
+/campaigns/:id                 # Campaign detail — live stats, progress bar, controls
+/campaigns/:id/results         # Structured results table + charts + export button
+```
+
+### Super Admin Pages
+
+```
+/admin/tenants                 # Tenant management — list, create, toggle features
+/admin/tenants/:id             # Tenant detail + agent provisioning + feature toggles
+/admin/system                  # System dashboard (health, queues, active calls)
+```
+
+---
+
+## Agent Template System
+
+### How Templates Work
+
+Each agent template is a module that defines:
+
+1. **Config schema** — what fields the tenant configures in the dashboard
+2. **Prompt builder** — generates the ElevenLabs system prompt from config
+3. **Config UI hint** — tells the React dashboard which form fields to render
+
+```typescript
+// templates/index.ts — Template registry
+import { receptionistTemplate } from './receptionist'
+import { surveyTemplate } from './survey'
+
+export const templates = {
+  receptionist: receptionistTemplate,
+  survey: surveyTemplate,
+  // Add new templates here — no other code changes needed
+}
+
+export function buildPrompt(agent: Agent): string {
+  const template = templates[agent.agent_template]
+  if (!template) throw new Error(`Unknown template: ${agent.agent_template}`)
+  return template.buildPrompt(agent.config)
+}
+```
+
+```typescript
+// templates/receptionist.ts
+export const receptionistTemplate = {
+  name: 'receptionist',
+  direction: 'inbound',
+
+  configSchema: {
+    business_name: { type: 'string', required: true },
+    business_hours: { type: 'array', items: { day: 'string', open: 'string', close: 'string' } },
+    transfer_number: { type: 'string', required: false },
+    faq_entries: { type: 'array', items: { question: 'string', answer: 'string' } },
+    services: { type: 'array', items: 'string' },
+  },
+
+  defaultPostCallProcessing: {
+    strategy: 'summarize',
+    whatsapp_notify: true,
+    notification_template: 'call_summary',
+  },
+
+  buildPrompt(config): string {
+    return `You are a receptionist for ${config.template_data.business_name}.
+Business hours: ${JSON.stringify(config.template_data.business_hours)}
+Services offered: ${config.template_data.services.join(', ')}
+
+FAQ:
+${config.template_data.faq_entries.map(f => `Q: ${f.question}\nA: ${f.answer}`).join('\n\n')}
+
+If the caller needs something you cannot handle, transfer to: ${config.template_data.transfer_number}
+${config.greeting}`
+  }
+}
+```
+
+```typescript
+// templates/survey.ts
+export const surveyTemplate = {
+  name: 'survey',
+  direction: 'outbound',
+
+  configSchema: {
+    intro_script: { type: 'string', required: true },
+    outro_script: { type: 'string', required: true },
+    default_survey_id: { type: 'ObjectId', required: false },
+  },
+
+  defaultPostCallProcessing: {
+    strategy: 'extract_survey',
+    whatsapp_notify: true,
+    notification_template: 'survey_progress',
+  },
+
+  // Prompt is built dynamically per campaign using the survey definition
+  buildPrompt(config, survey?): string {
+    const questions = survey?.questions.map(q =>
+      `${q.id}: ${q.text} (type: ${q.type}${q.options?.length ? ', options: ' + q.options.join('/') : ''})`
+    ).join('\n')
+
+    return `${config.template_data.intro_script}
+
+You are conducting a survey. Ask the following questions in order, respecting branch logic:
+${questions}
+
+When complete: ${config.template_data.outro_script}`
+  }
+}
+```
+
+### Adding a New Template
+
+To add a new use case (e.g., appointment reminder, debt collection, lead qualification):
+
+1. Create `templates/new-template.ts` with config schema + prompt builder
+2. Register it in `templates/index.ts`
+3. The dashboard auto-renders the correct config form via the schema
+4. No database migration. No route changes. No middleware changes.
+
+---
+
+## Post-Call Processing Pipeline
+
+This is the webhook flow triggered after every call. The pipeline reads from the agent's `post_call_processing` config — no hardcoded tenant type checks.
+
+```
+1. ElevenLabs call ends → POST /webhooks/elevenlabs
+   Payload: { agent_id, transcript, duration, metadata }
+
+2. Backend looks up agent by elevenlabs_agent_id
+   → Gets tenant, agent config, and post_call_processing settings
+
+3. Enqueue job to `post-call-processing` queue with:
+   {
+     call_id, transcript, agent_id, tenant_id,
+     strategy: agent.post_call_processing.strategy,
+     llm_provider: agent.post_call_processing.llm_provider,
+     survey_definition: (if strategy includes survey extraction, fetch from campaign)
+   }
+
+4. Worker picks up job and dispatches by strategy:
+
+   strategy: "summarize"
+   → LLM prompt: "Summarize this call. Extract: caller intent, key details,
+     action items, urgency level. Return as JSON."
+   → Save llm_summary to call record
+
+   strategy: "extract_survey"
+   → LLM prompt: "Given this survey definition: {questions}
+     And this call transcript: {transcript}
+     Extract the answer to each question. Return as JSON:
+     [{ question_id, answer, parsed_value }]"
+   → Save survey_responses to call record
+   → Update campaign stats
+
+   strategy: "summarize_and_extract"
+   → Run both prompts
+   → Save both llm_summary and survey_responses
+
+   strategy: "none"
+   → Save call record with transcript only, skip LLM
+
+5. If agent.post_call_processing.whatsapp_notify == true:
+   → Enqueue WhatsApp notification job
+   → Template selected by agent.post_call_processing.notification_template:
+     "call_summary": "New call from {number}. Summary: {llm_summary}"
+     "survey_progress": "Campaign {name}: {completed}/{total} completed"
+
+6. Log billing event (call_charge)
+```
+
+---
+
+## BullMQ Job Queues
+
+### Queue: `campaign-dialer`
+
+Handles outbound call scheduling and execution.
+
+```typescript
+// Job data
+{
+  campaign_id: string,
+  phone_number: string,
+  attempt: number
+}
+
+// Worker logic:
+// 1. Check if campaign is still "running"
+// 2. Check if within schedule window (time of day, day of week)
+// 3. Tell Asterisk to originate call to this number via NetGSM
+// 4. Connect call to ElevenLabs agent configured for this campaign's survey
+// 5. On failure/no_answer: re-queue with delay if retries remaining
+```
+
+### Queue: `post-call-processing`
+
+Handles async LLM processing after calls. Strategy-driven, not type-driven.
+
+```typescript
+// Job data
+{
+  call_id: string,
+  transcript: string,
+  strategy: "summarize" | "extract_survey" | "summarize_and_extract" | "none",
+  llm_provider: "openai" | "gemini",
+  survey_definition?: object   // only when strategy includes survey extraction
+}
+
+// Worker logic:
+// 1. Dispatch to correct processing function based on strategy
+// 2. Call OpenAI/Gemini with appropriate prompt
+// 3. Parse structured response
+// 4. Update call record in MongoDB
+// 5. Enqueue WhatsApp notification if configured
+// 6. Update campaign stats if outbound call
+```
+
+### Queue: `whatsapp-notifications`
+
+Handles WhatsApp sending with rate limiting.
+
+```typescript
+// Job data
+{
+  tenant_id: string,
+  recipients: string[],
+  notification_template: string,
+  template_data: object   // variables to fill into the template
+}
+```
+
+---
+
+## Feature Gating — How It Works End-to-End
+
+### Backend
+
+```typescript
+// Tenant onboarding — superadmin sets features
+await Tenant.create({
+  name: "Dr. Yılmaz Clinic",
+  plan: "pro",
+  enabled_features: ["inbound_agent", "whatsapp_notifications"]
+})
+
+// Later, clinic wants outbound reminders — superadmin adds feature:
+await Tenant.updateOne(
+  { _id: tenantId },
+  { $addToSet: { enabled_features: "outbound_campaigns" } }
+)
+// No migration. No type change. Just a feature toggle.
+```
+
+### Route Protection
+
+```typescript
+// Survey routes — only accessible if tenant has survey_builder feature
+fastify.register(surveyRoutes, { prefix: '/surveys' })
+// Inside surveyRoutes:
+fastify.addHook('onRequest', requireFeature('survey_builder'))
+
+// Campaign routes — only accessible if tenant has outbound_campaigns feature
+fastify.register(campaignRoutes, { prefix: '/campaigns' })
+// Inside campaignRoutes:
+fastify.addHook('onRequest', requireFeature('outbound_campaigns'))
+```
+
+### Frontend
+
+```typescript
+// Auth response includes tenant features
+GET /auth/me → { user: {...}, tenant: { enabled_features: [...] } }
+
+// Feature context provider
+const { features } = useTenant()
+
+// Conditional rendering
+{features.includes('survey_builder') && <SurveySection />}
+{features.includes('outbound_campaigns') && <CampaignSection />}
+
+// Route protection
+<Route path="/surveys/*" element={
+  features.includes('survey_builder') ? <SurveyRoutes /> : <Navigate to="/dashboard" />
+} />
+```
+
+---
+
+## Development Phases
+
+### Phase 0: Foundation (Week 1)
+
+* [ ] Initialize Fastify + TypeScript project with the structure above
+* [ ] Set up MongoDB connection via Mongoose with all models and indexes
+* [ ] Set up Redis connection
+* [ ] Implement JWT auth (register, login, refresh, logout)
+* [ ] Implement RBAC middleware (requireRole)
+* [ ] Implement feature-gating middleware (requireFeature)
+* [ ] Set up Winston logger
+* [ ] Set up BullMQ with Redis (queue definitions, basic worker skeleton)
+* [ ] Environment config (.env typing and validation with zod or similar)
+* [ ] Basic error handling middleware
+* [ ] Agent template registry with receptionist and survey templates
+
+### Phase 1: Core Backend (Week 2)
+
+* [ ] Tenant CRUD routes
+* [ ] User management routes (invite, update role, delete)
+* [ ] Agent CRUD + config update routes
+* [ ] Agent template config validation (validate template_data against template schema)
+* [ ] Prompt builder — dispatches to correct template, generates ElevenLabs system prompt
+* [ ] Call listing and detail routes (with pagination and filters)
+* [ ] ElevenLabs webhook endpoint — receive post-call data
+* [ ] Post-call processing worker — strategy-driven (summarize / extract_survey / both / none)
+* [ ] LLM wrapper service (OpenAI + Gemini, switchable per agent config)
+* [ ] Twilio WhatsApp notification service + queue worker
+* [ ] Wire up: webhook → post-call-processing queue → WhatsApp notification queue
+
+### Phase 2: Survey & Campaign Engine (Week 3)
+
+* [ ] Survey CRUD routes with question/branching validation
+* [ ] Campaign CRUD routes
+* [ ] Campaign state machine (draft → scheduled → running → paused → completed)
+* [ ] Campaign dialer worker (BullMQ) — orchestrates outbound calls via Asterisk
+* [ ] Phone list upload and management (CSV upload endpoint)
+* [ ] Survey response extraction (LLM post-processing with extract_survey strategy)
+* [ ] Campaign stats aggregation and update logic
+* [ ] Results export endpoint (CSV/Excel generation)
+* [ ] Voicemail/answering machine detection handling
+
+### Phase 3: Billing Integration (Week 3-4)
+
+* [ ] Usage metering — track calls per tenant, calculate charges
+* [ ] Param payment integration (checkout initiation)
+* [ ] Param webhook handler (payment confirmation)
+* [ ] Billing event logging
+* [ ] Usage summary and history endpoints
+
+### Phase 4: React Dashboard — Core (Week 4-5)
+
+* [ ] React + Vite + TypeScript project setup
+* [ ] Auth pages (login, register)
+* [ ] Tenant context provider (loads enabled_features, gates UI)
+* [ ] Layout with feature-aware sidebar navigation
+* [ ] Dashboard overview page (call stats cards, recent calls, usage chart)
+* [ ] Call history page (table with filters, pagination, search)
+* [ ] Call detail page (transcript viewer, summary, survey responses if present, recording playback)
+* [ ] Settings pages:
+  * [ ] Agent config form — dynamically renders fields based on agent_template
+  * [ ] Notification preferences (gated by whatsapp_notifications feature)
+  * [ ] User management (invite, role assignment, remove)
+  * [ ] Billing (current usage, payment history, add funds via Param)
+
+### Phase 5: React Dashboard — Feature-Gated Pages (Week 5-6)
+
+* [ ] Survey list page (gated by survey_builder)
+* [ ] Survey builder page (add questions, set types, configure branching logic)
+* [ ] Survey preview/test
+* [ ] Campaign list page with status badges (gated by outbound_campaigns)
+* [ ] Campaign creation wizard (select survey → upload numbers → set schedule → review → launch)
+* [ ] Campaign detail page (live progress, stats, controls: start/pause/stop)
+* [ ] Campaign results page (structured response table, basic charts, export button)
+
+### Phase 6: Super Admin Panel (Week 6-7)
+
+* [ ] Super admin routes (tenant list, create, update)
+* [ ] Tenant feature toggle UI (enable/disable features per tenant)
+* [ ] Agent provisioning (assign phone number + template to tenant)
+* [ ] System health dashboard (active calls, queue depths, error rates)
+* [ ] Global usage statistics
+* [ ] Agent template management (view registered templates)
+
+### Phase 7: Hardening (Week 7-8)
+
+* [ ] Input validation on all routes (fastify schemas or zod)
+* [ ] Rate limiting on auth routes and webhooks
+* [ ] Webhook signature verification (ElevenLabs, Param)
+* [ ] KVKK compliance review (data retention policies, consent tracking)
+* [ ] Call recording consent handling
+* [ ] Error monitoring setup (Sentry or similar)
+* [ ] API documentation (Swagger/OpenAPI via fastify-swagger)
+* [ ] Load testing on campaign dialer (concurrent call limits)
+* [ ] ElevenLabs rate limit handling and graceful degradation
+* [ ] Backup strategy for MongoDB Atlas
+* [ ] End-to-end testing of full call flows (inbound + outbound)
+
+---
+
+## Environment Variables
+
+```env
+# Server
+PORT=3000
+NODE_ENV=production
+
+# MongoDB
+MONGODB_URI=mongodb+srv://...
+
+# Redis
+REDIS_URL=redis://...
+
+# JWT
+JWT_SECRET=your-secret-key
+JWT_REFRESH_SECRET=your-refresh-secret
+JWT_ACCESS_EXPIRY=15m
+JWT_REFRESH_EXPIRY=7d
+
+# ElevenLabs
+ELEVENLABS_API_KEY=...
+ELEVENLABS_WEBHOOK_SECRET=...
+
+# OpenAI
+OPENAI_API_KEY=...
+
+# Google Gemini
+GOOGLE_AI_API_KEY=...
+
+# Twilio (WhatsApp)
+TWILIO_ACCOUNT_SID=...
+TWILIO_AUTH_TOKEN=...
+TWILIO_WHATSAPP_FROM=whatsapp:+...
+
+# Param (Payment)
+PARAM_CLIENT_CODE=...
+PARAM_CLIENT_USERNAME=...
+PARAM_CLIENT_PASSWORD=...
+PARAM_GUID=...
+
+# NetGSM / Asterisk
+ASTERISK_ARI_URL=http://...
+ASTERISK_ARI_USERNAME=...
+ASTERISK_ARI_PASSWORD=...
+```
+
+---
+
+## Key Technical Notes
+
+1. **All routes are tenant-scoped.** Every query must filter by `tenant_id` from the JWT. Never allow cross-tenant data access.
+2. **Feature gating is the core access control pattern.** Routes check features via middleware. The dashboard checks features to render UI. Super admins toggle features per tenant. No hardcoded tenant types anywhere.
+3. **Agent templates are the extensibility mechanism.** New use cases = new templates. No database changes, no route changes, no middleware changes. Just a new file in `templates/` and a registration in the registry.
+4. **Post-call processing is strategy-driven.** The webhook handler reads the agent's `post_call_processing.strategy` and dispatches accordingly. Adding a new strategy = adding a new case in the worker.
+5. **The prompt builder is critical.** It takes structured agent config and dispatches to the correct template's `buildPrompt()`. This is where AI agent quality lives — invest in prompt engineering per template.
+6. **Campaign dialer must respect concurrency limits.** Both Asterisk trunk capacity and ElevenLabs concurrent session limits. Make `max_concurrent_calls` configurable per campaign and enforce globally via Redis counters.
+7. **Survey response extraction quality determines product value.** Invest in prompt engineering for the extract_survey strategy. Test edge cases: caller goes off-topic, gives ambiguous answers, skips questions, hangs up mid-survey.
+8. **WhatsApp notifications should be non-blocking.** Use the BullMQ queue, don't hold up the webhook response.
+9. **MongoDB transactions** are needed for campaign stat updates where you update both the call record and campaign stats atomically.