elevenlabs-webhook-nodejs 1.0.0

package/SYSTEM_OVERVIEW.md

@@ -0,0 +1,942 @@
+# Tektip VoiceAI SaaS Platform - Complete System Overview
+
+> Multi-tenant AI-powered voice call platform with ElevenLabs integration, survey campaigns, WhatsApp notifications, and billing.
+
+---
+
+## Table of Contents
+
+1. [Tech Stack](#1-tech-stack)
+2. [Architecture Overview](#2-architecture-overview)
+3. [Database Schemas](#3-database-schemas)
+4. [API Endpoints](#4-api-endpoints)
+5. [Authentication Flow](#5-authentication-flow)
+6. [Core Business Flows](#6-core-business-flows)
+7. [Third-Party Integrations](#7-third-party-integrations)
+8. [Middleware & Plugins](#8-middleware--plugins)
+9. [Frontend Pages & Routing](#9-frontend-pages--routing)
+10. [Frontend State Management](#10-frontend-state-management)
+11. [Environment Variables](#11-environment-variables)
+12. [Project Structure](#12-project-structure)
+13. [Deployment](#13-deployment)
+
+---
+
+## 1. Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| **Backend** | Fastify 5 + TypeScript 5.9 |
+| **Frontend** | React 19 + Vite 7 + TypeScript 5.9 |
+| **Styling** | Tailwind CSS v4 + shadcn/ui (New York style) |
+| **Database** | MongoDB via Mongoose 8 |
+| **Auth** | JWT dual-token (access + refresh) via @fastify/jwt + jsonwebtoken |
+| **AI** | OpenAI (gpt-5.4-mini) or Google Gemini (configurable) |
+| **Voice** | ElevenLabs (webhook-based post-call processing) |
+| **Messaging** | Twilio WhatsApp API |
+| **Validation** | Zod 4 |
+| **Logging** | Winston |
+| **Process Manager** | PM2 |
+| **Icons** | Lucide React |
+| **Toasts** | Sonner |
+| **HTTP Client** | Axios (frontend) |
+
+---
+
+## 2. Architecture Overview
+
+```
+                         +-------------------+
+                         |   ElevenLabs AI   |
+                         |  (Voice Agents)   |
+                         +--------+----------+
+                                  |
+                    POST /webhooks/elevenlabs     WebSocket (text-only)
+                    (HMAC-SHA256 signed)          (signed URL, 15min)
+                                  |                    |
+                                  v                    v
++------------+           +--------+----------+           +----------+
+|  React SPA | <-------> |   Fastify API     | <-------> | MongoDB  |
+| (Vite dev  |  /api/*   |   (port 3005)     |           |          |
+|  port 5173)|  proxy    |                   |           +----------+
++------------+           +---+-----+----+----+
+                             |     |    |
+                             v     v    v
+                      +------+-+  +--+------+  +----------+
+                      | OpenAI |  | Twilio  |  |  Unipile |
+                      | Gemini |  | WhatsApp|  | WhatsApp |
+                      +--------+  +---------+  +----------+
+```
+
+**Multi-tenant design**: Every data entity is scoped by `tenant_id`. All queries filter by tenant. Feature flags control which capabilities each tenant can use.
+
+**Role hierarchy**: `superadmin` > `admin` > `manager` > `viewer`
+
+---
+
+## 3. Database Schemas
+
+### 3.1 Tenant
+
+| Field | Type | Details |
+|-------|------|---------|
+| `name` | String | Required |
+| `plan` | String | `free` / `starter` / `pro` / `premium`, default: `free` |
+| `enabled_features` | [String] | Enum: `inbound_agent`, `outbound_campaigns`, `survey_builder`, `whatsapp_notifications`, `whatsapp_agent` |
+| `settings.whatsapp_agent.unipile_account_id` | String | Unipile WhatsApp account ID |
+| `settings.whatsapp_agent.unipile_account_status` | String | Connection status |
+| `settings.whatsapp_agent.agent_id` | ObjectId → Agent | Reference to the Agent model that handles WhatsApp AI (resolved to ElevenLabs agent ID at runtime, checks is_active) |
+| `settings.whatsapp_agent.connected_at` | Date | When WhatsApp was connected |
+| `settings.whatsapp_agent.connected_phone` | String | Connected phone number |
+| `settings.whatsapp_agent.grace_period_seconds` | Number | Default: 180 (seconds before AI takes over) |
+| `settings.whatsapp_agent.blacklisted_numbers` | [String] | Numbers excluded from AI |
+| `settings.kvkk_consent` | Boolean | Default: false |
+| `settings.notification_recipients` | [String] | Phone numbers |
+| `settings.default_language` | String | Default: `tr` |
+| `createdAt` / `updatedAt` | Date | Auto |
+
+### 3.2 User
+
+| Field | Type | Details |
+|-------|------|---------|
+| `tenant_id` | ObjectId → Tenant | Required, indexed |
+| `email` | String | Required, unique, lowercase, trimmed, indexed |
+| `password_hash` | String | Bcrypt, 12 salt rounds |
+| `role` | String | `superadmin` / `admin` / `manager` / `viewer`, default: `viewer` |
+| `name` | String | Required |
+| `createdAt` / `updatedAt` | Date | Auto |
+
+### 3.3 RefreshToken
+
+| Field | Type | Details |
+|-------|------|---------|
+| `user_id` | ObjectId → User | Required, indexed |
+| `token` | String | Required, unique |
+| `expires_at` | Date | Required, TTL index (auto-deletes expired tokens) |
+| `createdAt` | Date | Auto |
+
+### 3.4 Agent
+
+| Field | Type | Details |
+|-------|------|---------|
+| `tenant_id` | ObjectId → Tenant | Required, indexed |
+| `phone_number` | String | Required |
+| `elevenlabs_agent_id` | String | Required, indexed |
+| `direction` | String | `inbound` / `outbound` / `both` |
+| `agent_template` | String | `receptionist` / `survey` / `custom` |
+| `config.voice_id` | String | Required |
+| `config.language` | String | Default: `tr` |
+| `config.greeting` | String | Default: `''` |
+| `config.template_data` | Mixed | Template-specific data |
+| `post_call_processing.strategy` | String | `summarize` / `extract_survey` / `summarize_and_extract` / `none` |
+| `post_call_processing.llm_provider` | String | `openai` / `gemini` |
+| `post_call_processing.whatsapp_notify` | Boolean | Default: true |
+| `post_call_processing.notification_template` | String | `call_summary` / `survey_progress` / `custom` |
+| `is_active` | Boolean | Default: true |
+| `createdAt` / `updatedAt` | Date | Auto |
+
+### 3.5 Call
+
+| Field | Type | Details |
+|-------|------|---------|
+| `tenant_id` | ObjectId → Tenant | Required |
+| `agent_id` | ObjectId → Agent | Required |
+| `campaign_id` | ObjectId → Campaign | Nullable |
+| `direction` | String | `inbound` / `outbound` |
+| `caller_number` | String | Required |
+| `callee_number` | String | Required |
+| `duration_seconds` | Number | Default: 0 |
+| `status` | String | `completed` / `failed` / `no_answer` / `voicemail` / `transferred` |
+| `transcript` | String | Default: `''` |
+| `llm_summary` | String | Nullable |
+| `survey_responses` | Array | `[{ question_id, question_text, answer, parsed_value }]` |
+| `whatsapp_notification_sent` | Boolean | Default: false |
+| `recording_url` | String | Nullable |
+| `createdAt` | Date | Auto |
+
+**Indexes**: `(tenant_id, createdAt)`, `(campaign_id, status)`, `(tenant_id, direction, createdAt)`
+
+### 3.6 Survey
+
+| Field | Type | Details |
+|-------|------|---------|
+| `tenant_id` | ObjectId → Tenant | Required, indexed |
+| `name` | String | Required |
+| `description` | String | Default: `''` |
+| `questions` | Array | See below |
+| `status` | String | `draft` / `active` / `archived`, default: `draft` |
+| `createdAt` / `updatedAt` | Date | Auto |
+
+**Question schema**: `{ id, text, type (open/multiple_choice/rating/yes_no), options: [String], required: Boolean, branch_logic: { condition, go_to } | null }`
+
+### 3.7 Campaign
+
+| Field | Type | Details |
+|-------|------|---------|
+| `tenant_id` | ObjectId → Tenant | Required |
+| `survey_id` | ObjectId → Survey | Required |
+| `agent_id` | ObjectId → Agent | Required |
+| `name` | String | Required |
+| `status` | String | `draft` / `scheduled` / `running` / `paused` / `completed` |
+| `phone_list` | Array | `[{ number, status, attempts, last_attempt_at }]` |
+| `schedule.start_date` | Date | Required |
+| `schedule.end_date` | Date | Required |
+| `schedule.daily_start_time` | String | Default: `09:00` |
+| `schedule.daily_end_time` | String | Default: `18:00` |
+| `schedule.days_of_week` | [Number] | Default: `[1,2,3,4,5]` (Mon-Fri) |
+| `schedule.max_concurrent_calls` | Number | Default: 1 |
+| `schedule.max_retries` | Number | Default: 3 |
+| `schedule.retry_delay_minutes` | Number | Default: 60 |
+| `stats` | Object | `{ total, completed, failed, no_answer, voicemail, pending }` |
+| `createdAt` / `updatedAt` | Date | Auto |
+
+**Index**: `(tenant_id, status)`
+**State machine**: `draft → scheduled → running → paused/completed`, `paused → running/completed`
+
+### 3.8 BillingEvent
+
+| Field | Type | Details |
+|-------|------|---------|
+| `tenant_id` | ObjectId → Tenant | Required |
+| `type` | String | `call_charge` / `subscription` / `top_up` / `refund` |
+| `amount` | Number | Required |
+| `currency` | String | Default: `TRY` |
+| `call_id` | ObjectId → Call | Nullable |
+| `param_transaction_id` | String | Nullable |
+| `description` | String | Default: `''` |
+| `createdAt` | Date | Auto |
+
+**Index**: `(tenant_id, createdAt)`
+**Pricing**: 1.5 TRY per minute (rounded up)
+
+### 3.9 WhatsAppChat
+
+| Field | Type | Details |
+|-------|------|---------|
+| `tenant_id` | ObjectId → Tenant | Required, indexed |
+| `unipile_chat_id` | String | Required, unique |
+| `unipile_account_id` | String | Unipile account this chat belongs to |
+| `contact_name` | String | Contact's display name |
+| `contact_phone` | String | Contact's phone number |
+| `is_closed` | Boolean | Whether chat has been manually closed (default: false) |
+| `active_session_id` | ObjectId → WhatsAppSession | Current active session (null if no session) |
+| `last_message_at` | Date | Timestamp of most recent message |
+| `last_message_preview` | String | First 100 chars of last message |
+| `message_count` | Number | Total messages in chat |
+| `createdAt` / `updatedAt` | Date | Auto |
+
+**Indexes**: `(tenant_id, last_message_at)`, `(unipile_chat_id)` unique
+
+### 3.10 WhatsAppSession
+
+Tracks the lifecycle of a human/AI conversation session within a chat. Each new contact interaction starts a session with a grace period where humans get first chance to respond.
+
+| Field | Type | Details |
+|-------|------|---------|
+| `chat_id` | ObjectId → WhatsAppChat | Required |
+| `tenant_id` | ObjectId → Tenant | Required |
+| `status` | String | `waiting` / `active` / `resolved` |
+| `resolved_by` | String | `human` / `ai_timeout` / `manual` / `timeout` / null |
+| `started_at` | Date | When session was created |
+| `resolved_at` | Date | When session ended (null if still open) |
+| `grace_deadline` | Date | When AI takes over if human doesn't respond |
+| `taken_over_by` | ObjectId → User | User who took over (null = AI mode) |
+| `taken_over_at` | Date | When takeover happened |
+| `elevenlabs_conversation_id` | String | Active ElevenLabs conversation (null until AI connects) |
+| `elevenlabs_conversation_created_at` | Date | When EL conversation was created |
+| `elevenlabs_last_interaction_at` | Date | Last message sent to EL |
+| `message_count` | Number | Messages in this session |
+| `createdAt` / `updatedAt` | Date | Auto |
+
+**Indexes**: `(chat_id, status)`, `(status, grace_deadline)`, `(tenant_id, status)`
+
+**Session lifecycle**:
+```
+Contact sends message
+       │
+       ▼
+   [waiting] ─── grace period timer (e.g. 180s) ───→ [active] (AI takes over)
+       │                                                  │
+       │ Human responds                                   │ Human takeover button
+       ▼                                                  ▼
+   [resolved]                                        [active] (human mode)
+   resolved_by='human'                               taken_over_by=<userId>
+                                                          │
+                                                          │ Release / Close
+                                                          ▼
+                                                      [resolved]
+                                                      resolved_by='manual'
+```
+
+### 3.11 WhatsAppMessage
+
+| Field | Type | Details |
+|-------|------|---------|
+| `chat_id` | ObjectId → WhatsAppChat | Required |
+| `session_id` | ObjectId → WhatsAppSession | Nullable (null for blacklisted/legacy) |
+| `tenant_id` | ObjectId → Tenant | Required |
+| `unipile_message_id` | String | Unipile's message ID (null for AI responses) |
+| `sender` | String | `contact` / `ai` / `human` |
+| `sender_name` | String | Display name of sender |
+| `text` | String | Message content |
+| `sent_via_unipile` | Boolean | Whether sent through Unipile API |
+| `createdAt` | Date | Auto |
+
+**Indexes**: `(chat_id, createdAt)`, `(session_id, createdAt)`
+
+### 3.12 Legacy Models (still in codebase)
+
+- **Transcription** - Raw ElevenLabs transcription storage with processing pipeline status
+- **Summary** - AI-generated call summaries with sentiment analysis
+- **WhatsAppRecipient** - Notification recipients with agent/duration filters
+
+---
+
+## 4. API Endpoints
+
+### 4.1 Auth (`/auth`)
+
+| Method | Path | Auth | Role | Description |
+|--------|------|------|------|-------------|
+| POST | `/auth/register` | - | - | Create tenant + first admin user. Returns tokens. |
+| POST | `/auth/login` | - | - | Email/password login. Returns tokens + user + tenant. |
+| POST | `/auth/refresh` | - | - | Rotate refresh token, get new access token. |
+| POST | `/auth/logout` | Yes | Any | Revoke refresh token. |
+| GET | `/auth/me` | Yes | Any | Current user profile + tenant info. |
+
+### 4.2 Users (`/users`)
+
+| Method | Path | Auth | Role | Description |
+|--------|------|------|------|-------------|
+| GET | `/users` | Yes | Any | List users in tenant. |
+| POST | `/users/invite` | Yes | admin | Invite new user (email, password, name, role). |
+| PUT | `/users/:id` | Yes | admin | Update user role/name. |
+| DELETE | `/users/:id` | Yes | admin | Delete user (cannot self-delete). |
+
+### 4.3 Tenants (`/tenants`)
+
+| Method | Path | Auth | Role | Description |
+|--------|------|------|------|-------------|
+| GET | `/tenants/me` | Yes | Any | Get current tenant. |
+| PUT | `/tenants/me` | Yes | admin | Update tenant name/settings. |
+
+### 4.4 Agents (`/agents`)
+
+| Method | Path | Auth | Role | Description |
+|--------|------|------|------|-------------|
+| GET | `/agents` | Yes | Any | List agents for tenant. |
+| GET | `/agents/:id` | Yes | Any | Get agent detail. |
+| PUT | `/agents/:id/config` | Yes | admin | Update agent config / post-call processing. |
+| POST | `/agents/:id/toggle` | Yes | admin | Enable/disable agent. |
+
+### 4.5 Calls (`/calls`)
+
+| Method | Path | Auth | Role | Description |
+|--------|------|------|------|-------------|
+| GET | `/calls` | Yes | Any | Paginated list. Filters: `direction`, `status`, `agent_id`, `from`, `to`. |
+| GET | `/calls/stats` | Yes | Any | Aggregated stats: total, completed, failed, avg duration, etc. |
+| GET | `/calls/:id` | Yes | Any | Call detail with transcript, summary, survey responses. |
+
+### 4.6 Surveys (`/surveys`)
+
+| Method | Path | Auth | Role | Feature | Description |
+|--------|------|------|------|---------|-------------|
+| GET | `/surveys` | Yes | Any | `survey_builder` | List surveys. |
+| POST | `/surveys` | Yes | admin/mgr | `survey_builder` | Create survey. |
+| GET | `/surveys/:id` | Yes | Any | `survey_builder` | Survey detail with questions. |
+| PUT | `/surveys/:id` | Yes | admin/mgr | `survey_builder` | Update survey. |
+| DELETE | `/surveys/:id` | Yes | admin/mgr | `survey_builder` | Delete (fails if active campaigns exist). |
+| POST | `/surveys/:id/duplicate` | Yes | admin/mgr | `survey_builder` | Duplicate survey. |
+
+### 4.7 Campaigns (`/campaigns`)
+
+| Method | Path | Auth | Role | Feature | Description |
+|--------|------|------|------|---------|-------------|
+| GET | `/campaigns` | Yes | Any | `outbound_campaigns` | Paginated list. Filter: `status`. |
+| POST | `/campaigns` | Yes | admin/mgr | `outbound_campaigns` | Create campaign (name, survey, agent, schedule). |
+| GET | `/campaigns/:id` | Yes | Any | `outbound_campaigns` | Detail with populated survey/agent. |
+| PUT | `/campaigns/:id` | Yes | admin/mgr | `outbound_campaigns` | Update (draft/scheduled only). |
+| POST | `/campaigns/:id/start` | Yes | admin/mgr | `outbound_campaigns` | Start campaign. |
+| POST | `/campaigns/:id/pause` | Yes | admin/mgr | `outbound_campaigns` | Pause campaign. |
+| POST | `/campaigns/:id/resume` | Yes | admin/mgr | `outbound_campaigns` | Resume campaign. |
+| POST | `/campaigns/:id/stop` | Yes | admin/mgr | `outbound_campaigns` | Stop permanently. |
+| POST | `/campaigns/:id/phone-list` | Yes | admin/mgr | `outbound_campaigns` | Upload phone numbers (array or CSV). |
+| GET | `/campaigns/:id/results` | Yes | Any | `outbound_campaigns` | Campaign results with survey responses. |
+| GET | `/campaigns/:id/results/export` | Yes | Any | `outbound_campaigns` | Export results as CSV download. |
+
+### 4.8 Billing (`/billing`)
+
+| Method | Path | Auth | Role | Description |
+|--------|------|------|------|-------------|
+| GET | `/billing/usage` | Yes | admin | Current month: total calls, duration, charges. |
+| GET | `/billing/history` | Yes | admin | Paginated billing events. Filter: `type`. |
+
+### 4.9 Admin - SuperAdmin Only (`/admin`)
+
+| Method | Path | Auth | Role | Description |
+|--------|------|------|------|-------------|
+| GET | `/admin/tenants` | Yes | superadmin | List all tenants with user_count. Filters: `search`, `page`. |
+| POST | `/admin/tenants` | Yes | superadmin | Create tenant. |
+| GET | `/admin/tenants/:id` | Yes | superadmin | Tenant detail: users, agents, call/campaign counts. |
+| PUT | `/admin/tenants/:id` | Yes | superadmin | Update tenant (name, plan, features, settings). |
+| PUT | `/admin/tenants/:id/features` | Yes | superadmin | Toggle tenant features. |
+| POST | `/admin/agents` | Yes | superadmin | Provision agent for a tenant. |
+| GET | `/admin/system/health` | Yes | superadmin | System: uptime, tenant/user/agent/call counts, revenue. |
+| GET | `/admin/system/usage` | Yes | superadmin | Per-tenant usage this month. |
+| GET | `/admin/templates` | Yes | superadmin | List available agent templates. |
+
+### 4.10 WhatsApp Agent (`/whatsapp`) — Feature: `whatsapp_agent`
+
+**Connection Management**:
+
+| Method | Path | Auth | Role | Description |
+|--------|------|------|------|-------------|
+| POST | `/whatsapp/connect` | Yes | admin | Initiate WhatsApp QR code connection via Unipile |
+| GET | `/whatsapp/connection-status` | Yes | Any | Check Unipile account connection status |
+| POST | `/whatsapp/disconnect` | Yes | admin | Disconnect WhatsApp account |
+| PUT | `/whatsapp/config` | Yes | admin | Set `agent_id` (ObjectId → Agent) and/or `grace_period_seconds` |
+| GET | `/whatsapp/agents` | Yes | admin | List tenant's agents for selection dropdown |
+| POST | `/whatsapp/register-webhook` | Yes | admin | Register Unipile webhook URL |
+
+**Blacklist Management**:
+
+| Method | Path | Auth | Role | Description |
+|--------|------|------|------|-------------|
+| GET | `/whatsapp/blacklist` | Yes | admin/mgr | Get blacklisted numbers |
+| POST | `/whatsapp/blacklist` | Yes | admin/mgr | Add phone to blacklist |
+| DELETE | `/whatsapp/blacklist/:phone` | Yes | admin/mgr | Remove phone from blacklist |
+
+**Chat Management**:
+
+| Method | Path | Auth | Role | Description |
+|--------|------|------|------|-------------|
+| GET | `/whatsapp/stats` | Yes | Any | Chat/session statistics (total, AI, human, waiting, closed) |
+| GET | `/whatsapp/chats` | Yes | Any | Paginated list. Filter: `mode` (ai/human/closed). Enriched with session info. |
+| GET | `/whatsapp/chats/:id` | Yes | Any | Chat detail (enriched with mode/session_status from active session) |
+| GET | `/whatsapp/chats/:id/messages` | Yes | Any | Paginated messages |
+| GET | `/whatsapp/chats/:id/sessions` | Yes | Any | Paginated session history for a chat |
+| POST | `/whatsapp/chats/:id/takeover` | Yes | admin/mgr | Human takes over from AI |
+| POST | `/whatsapp/chats/:id/release` | Yes | admin/mgr | Release back to AI. Body: `{ immediate?: boolean }` |
+| POST | `/whatsapp/chats/:id/close` | Yes | admin/mgr | Close chat (resolves active session) |
+| POST | `/whatsapp/chats/:id/reopen` | Yes | admin/mgr | Reopen closed chat |
+| POST | `/whatsapp/chats/:id/send` | Yes | admin/mgr | Send manual message (human mode only). If session is `waiting`, resolves it as human. |
+
+**Note**: The `enrichChat()` function derives backward-compatible virtual fields from the active session:
+- `mode` → `'ai'` (no session or active+no takeover), `'human'` (waiting or taken over), `'closed'` (is_closed)
+- `session_status` → `'waiting'` (grace period) or `'idle'` (all other states)
+- `taken_over_by`, `taken_over_at`, `session_started_at`, `session_grace_deadline`
+- Removes internal fields (`active_session_id`, `is_closed`) and aggregation pipeline temporaries (`_session`, `_activeSession`, `_mode`)
+
+### 4.11 Webhooks
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/webhooks/elevenlabs` | Signature (HMAC-SHA256) | ElevenLabs post-call webhook. Returns 200 immediately, processes async. |
+| POST | `/webhooks/unipile` | Shared secret header | Unipile WhatsApp message webhook. Returns 200 immediately, processes async. |
+
+### 4.11 Health & Legacy
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/health` | - | Health check: `{ status: 'ok', timestamp }` |
+| GET | `/whatsapp/status` | - | WhatsApp service status. |
+| POST | `/legacy-admin/login` | - | Legacy admin auth (password only). |
+| GET/POST/PUT/PATCH/DELETE | `/legacy-admin/*` | JWT | Legacy recipient & transcription CRUD. |
+
+---
+
+## 5. Authentication Flow
+
+### Dual-Token JWT System
+
+```
+Register/Login
+      |
+      v
++-----+-------+     +----------+
+| Access Token |     | Refresh  |
+| (JWT, 15min) |     | Token    |
+| in-memory /  |     | (JWT,7d) |
+| localStorage |     | DB-stored|
++--------------+     +----------+
+      |                    |
+      |  On 401            |
+      |  +--------+        |
+      +->| Retry  |<-------+  POST /auth/refresh
+         | with   |           (old token revoked,
+         | new AT |            new pair issued)
+         +--------+
+```
+
+**Access token payload**: `{ id, tenant_id, role, enabled_features }`
+**Refresh token payload**: `{ id, type: 'refresh' }`
+
+**Security measures**:
+- Bcrypt (12 rounds) password hashing
+- Token rotation on every refresh (old token revoked)
+- MongoDB TTL index auto-deletes expired refresh tokens
+- `requireFeature` middleware re-fetches tenant from DB (prevents stale JWT features)
+- Users cannot delete themselves or change their own role
+
+---
+
+## 6. Core Business Flows
+
+### 6.1 Inbound Call Flow (Webhook Processing)
+
+```
+1. Phone call comes in → ElevenLabs AI agent handles it
+2. Call ends → ElevenLabs sends POST /webhooks/elevenlabs
+3. Signature validated (HMAC-SHA256, 30-min timestamp tolerance)
+4. Agent looked up by elevenlabs_agent_id
+5. Call record created in DB
+6. Post-call processing (based on agent.post_call_processing.strategy):
+   ├── "summarize"             → AI generates summary
+   ├── "extract_survey"        → AI extracts survey responses
+   ├── "summarize_and_extract" → Both
+   └── "none"                  → Skip
+7. WhatsApp notification sent (if whatsapp_notify=true)
+8. Billing event logged (1.5 TRY/min, rounded up)
+```
+
+### 6.2 Outbound Campaign Flow
+
+```
+1. Create Survey → define questions (open/multiple_choice/rating/yes_no)
+2. Set survey status to "active"
+3. Create Campaign → link survey + agent + schedule
+4. Upload phone list (paste numbers or CSV)
+5. Start campaign (draft → scheduled → running)
+6. For each phone number:
+   ├── ElevenLabs agent calls the number
+   ├── Call ends → webhook fires → Call record created
+   ├── Survey responses extracted from transcript
+   └── Phone list entry status updated
+7. View results → table with responses per phone number
+8. Export results as CSV
+```
+
+### 6.3 Campaign State Machine
+
+```
+draft ──→ scheduled ──→ running ──→ completed
+                           │
+                           ↓
+                        paused ──→ running
+                           │
+                           └──→ completed
+```
+
+### 6.4 Registration Flow
+
+```
+1. User submits: email, password, name, tenant_name
+2. Tenant created: plan=free, features=[inbound_agent, whatsapp_notifications]
+3. User created: role=admin, linked to tenant
+4. Access + refresh tokens issued
+5. User lands on dashboard
+```
+
+### 6.5 WhatsApp Agent Flow (Session-Based Architecture)
+
+The WhatsApp Agent system uses a **grace period** pattern: when a contact sends a message, a session is created in `waiting` state. Humans get first chance to respond. If no human responds before the deadline, AI takes over.
+
+```
+Contact sends WhatsApp message
+         │
+    ┌────▼────────────────────────────────────────────────┐
+    │  Unipile webhook → POST /webhooks/unipile           │
+    │  1. Find/create WhatsAppChat                        │
+    │  2. Check blacklist (if blacklisted → store only)   │
+    │  3. Look up active session                          │
+    └────┬────────────────────────────────────────────────┘
+         │
+    ┌────┴───────────────┐
+    │                    │
+No Active Session    Session Exists
+    │                    │
+    ▼                    │
+Create WhatsAppSession   │
+status='waiting'         │
+grace_deadline=now+180s  │
+    │                    │
+    ├────────────────────┤
+    │                    │
+    │  ┌─────────────────┴──────────────────┐
+    │  │                                    │
+    │  status='waiting'              status='active'
+    │  Store msg, timer running      Forward to AI agent
+    │  │                             (or skip if human-taken)
+    │  │
+    │  │     ┌──── Human responds in WhatsApp ────┐
+    │  │     │  → resolveSessionAsHuman()          │
+    │  │     │  → cancel timer, status='resolved'  │
+    │  │     └─────────────────────────────────────┘
+    │  │
+    │  │     ┌──── Human clicks "Takeover" in UI ──┐
+    │  │     │  → set taken_over_by, close EL WS   │
+    │  │     │  → session stays 'active' (human)    │
+    │  │     └──────────────────────────────────────┘
+    │  │
+    │  └──── Grace period expires (no human response) ───┐
+    │        → session status='active' (AI)               │
+    │        → replayPendingMessages()                    │
+    │        → create ElevenLabs WebSocket (text-only)    │
+    │        → send context + combined messages           │
+    │        → AI responds → send via Unipile             │
+    └─────────────────────────────────────────────────────┘
+```
+
+**Key components**:
+- **WhatsAppAgentService** (`src/services/whatsapp-agent.service.ts`): Manages grace period timers (in-memory `Map<sessionId, Timeout>`), ElevenLabs WebSocket connections, message replay, and session recovery on startup
+- **createSession()** in webhook handler: Creates `WhatsAppSession`, links to chat via `active_session_id`
+- **enrichChat()** in routes: Derives `mode`/`session_status` from active session for backward-compatible API responses
+- **Stuck session sweeper**: Every 5min, finds sessions stuck in `waiting` past deadline without timers
+- **Idle connection cleanup**: Every 1min, closes ElevenLabs WebSocket connections idle > 10min
+- **Conversation timeout**: If ElevenLabs conversation is > 30min old, starts fresh one
+
+**Message buffer**: 20-second debounce — contact messages are buffered, timer resets on each new message, combined text sent to AI after 20s of silence.
+
+**WebSocket reconnection**: Auto-reconnect with exponential backoff (1.5s, 3s, 6s, max 3 retries) on unexpected WS close.
+
+**Inactivity auto-resolve**: Active sessions with no activity for 30 minutes auto-resolve as `timeout`.
+
+**Agent reference**: ElevenLabs agent ID is now resolved through the Agent model (checks `is_active`).
+
+**Release dialog** (frontend): When releasing a chat back to AI, user can choose:
+- "Hemen Yanit Ver" (Respond Immediately) — replays pending messages to AI
+- "Mesaj Bekle" (Wait for Message) — releases without triggering AI
+
+---
+
+## 7. Third-Party Integrations
+
+### ElevenLabs (Voice AI)
+- **Purpose**: AI voice agents for inbound/outbound calls
+- **Integration**: Webhook-based (POST /webhooks/elevenlabs)
+- **Auth**: HMAC-SHA256 signature validation
+- **Events processed**: `post_call_transcription`
+- **Data received**: conversation_id, agent_id, transcript, metadata, call status
+
+### OpenAI
+- **Purpose**: Call summarization & survey response extraction
+- **Model**: gpt-5.4-mini (configurable via env)
+- **Temperature**: 0.3
+- **Features**: Token usage tracking, custom prompts per agent (via agentPrompts.json)
+
+### Google Gemini
+- **Purpose**: Alternative AI provider for summarization
+- **Model**: gemini-pro (configurable)
+- **Usage**: Swappable with OpenAI via `AI_PROVIDER` env var
+
+### Twilio WhatsApp
+- **Purpose**: Post-call notifications to recipients
+- **Method**: Template-based messages (template SID: HX47645724f174e91c4d90b25ee10fe612)
+- **Variables**: caller_number, call_summary
+- **Features**: Recipient filters (agent_ids, min_call_duration), notification tracking
+
+### Unipile (WhatsApp Messaging)
+- **Purpose**: WhatsApp message relay for the AI agent chat system
+- **Integration**: REST API + webhooks
+- **Auth**: API key (`UNIPILE_API_KEY`)
+- **Connection flow**: `POST /api/v1/accounts` → returns QR code → user scans → account connected
+- **Capabilities**:
+  - `connectWhatsApp()` — Create new WhatsApp account (returns QR code checkpoint)
+  - `reconnectAccount(id)` — Reconnect existing account
+  - `getAccountStatus(id)` — Check connection status
+  - `sendMessage(chatId, text)` — Send WhatsApp message
+  - `createWebhook(url)` — Register webhook for incoming messages
+- **Webhook payload**: `{ account_id, event, chat_id, message_id, message, is_sender, sender, attendees }`
+- **Webhook secret**: Optional `x-unipile-secret` header validation
+
+### ElevenLabs WebSocket (WhatsApp Chat AI)
+- **Purpose**: Real-time text-only AI conversations for WhatsApp agent
+- **Integration**: Signed WebSocket URL (15min expiry)
+- **Flow**: `getSignedUrl({ agentId })` → WebSocket connect with `?textOnly=true`
+- **Messages**:
+  - `conversation_initiation_metadata` — Connection ready, contains conversation_id
+  - `user_message` — Send contact's message to AI
+  - `agent_response` — AI's reply (forwarded to contact via Unipile)
+  - `contextual_update` — Send conversation history for context
+- **First message suppression**: Agent greeting is suppressed (only real responses sent)
+- **Conversation timeout**: 30min idle → new conversation created
+
+---
+
+## 8. Middleware & Plugins
+
+| Plugin/Middleware | File | Purpose |
+|-------------------|------|---------|
+| **JWT Plugin** | `src/plugins/jwt.ts` | Registers @fastify/jwt, provides `fastify.authenticate` decorator |
+| **RBAC - requireRole** | `src/plugins/rbac.ts` | Role-based access control. Superadmin bypasses all. Returns 403. |
+| **RBAC - requireFeature** | `src/plugins/rbac.ts` | Feature flag check. Fetches tenant from DB (not JWT). Returns 403. |
+| **CORS** | `src/plugins/cors.ts` | @fastify/cors with defaults |
+| **Raw Body** | `src/plugins/rawBody.ts` | Stores raw body for webhook signature validation |
+| **Webhook Validator** | `src/hooks/webhookValidator.ts` | HMAC-SHA256 signature + timestamp check (30-min window) |
+
+---
+
+## 9. Frontend Pages & Routing
+
+### Route Structure (React Router v6)
+
+```
+/ → redirect to /dashboard
+├── /login                    Public - email/password login
+├── /register                 Public - signup with company name
+└── <ProtectedRoute> + <Layout>
+    ├── /dashboard            Stats cards, recent calls, usage summary
+    ├── /calls                Call list with direction/status filters, pagination
+    ├── /calls/:id            Call detail: transcript, AI summary, survey responses
+    ├── /surveys              Survey list with duplicate/delete actions
+    ├── /surveys/:id          Survey builder: add/edit/delete questions
+    ├── /surveys/:id/preview  Interactive survey preview
+    ├── /campaigns            Campaign list with status filter, progress bars
+    ├── /campaigns/new        3-step wizard: Info → Schedule → Phone list
+    ├── /campaigns/:id        Campaign detail with start/pause/resume/stop
+    ├── /campaigns/:id/results Results table + CSV export
+    ├── /whatsapp             WhatsApp two-panel layout: chat list + detail
+    ├── /whatsapp/:chatId     Same WhatsApp component (two-panel), detail panel shows selected chat
+    ├── /settings             Tabs: Company settings + User management
+    ├── /billing              Usage summary + transaction history
+    ├── /admin/tenants        [superadmin] Tenant list with search
+    ├── /admin/tenants/:id    [superadmin] Tenant detail: users, agents, stats
+    └── /admin/system         [superadmin] System health, uptime, usage
+```
+
+**Note**: Both `/whatsapp` and `/whatsapp/:chatId` render the same `WhatsApp` component (two-panel layout). The WhatsApp UI is composed of 10 dedicated components in `web/src/components/whatsapp/`.
+
+### Layout Shell
+- Collapsible sidebar with navigation icons
+- User dropdown menu (profile, logout)
+- Conditional nav items based on `enabled_features` and `role`
+- Sonner toast notifications (top-right)
+
+### Shared Components
+
+| Component | Props | Purpose |
+|-----------|-------|---------|
+| `PageHeader` | title, description?, children? | Page title + optional action buttons |
+| `StatCard` | label, value, icon?, className? | Metric display card |
+| `PageLoader` | - | Skeleton loading state |
+| `TableLoader` | rows?, cols? | Table skeleton |
+| `EmptyState` | message, icon? | Empty data state |
+| `Pagination` | page, totalPages, onPageChange | Prev/next navigation |
+| `CallStatusBadge` | status | Colored badge for call status |
+| `CampaignStatusBadge` | status | Colored badge for campaign status |
+| `SurveyStatusBadge` | status | Colored badge for survey status |
+| `DirectionBadge` | direction | inbound (sky) / outbound (violet) |
+| `BillingTypeBadge` | type | Badge for billing event type |
+| `ChatModeBadge` | mode | AI (green) / Human (amber) / Closed (gray) |
+| `SessionStatusBadge` | status | Shows "Bekleniyor" badge only when status='waiting' |
+
+---
+
+## 10. Frontend State Management
+
+**Approach**: React hooks only (no Redux/Zustand)
+
+### AuthContext (Global)
+```typescript
+{
+  user: User | null
+  tenant: Tenant | null
+  isLoading: boolean
+  login(email, password): Promise<void>
+  register(email, password, name, tenantName): Promise<void>
+  logout(): Promise<void>
+}
+```
+
+**`useFeature(feature)`** hook: checks `tenant.enabled_features` for conditional rendering.
+
+### API Client (`/lib/api.ts`)
+- Axios instance with baseURL `/api`
+- Request interceptor: attaches `Authorization: Bearer {token}`
+- Response interceptor: on 401 → refresh token → retry request → on failure → redirect to `/login`
+
+### Data Fetching Pattern
+- `useState` + `useEffect` for API calls on mount/param change
+- `useSearchParams` for pagination and filter state in URL
+- No caching layer (direct API calls)
+
+---
+
+## 11. Environment Variables
+
+```bash
+# Server
+PORT=3005                              # Backend port
+NODE_ENV=development                   # development | production
+
+# Database
+MONGODB_URI=mongodb://localhost:27017/elevenlabs-webhook
+
+# ElevenLabs
+ELEVENLABS_WEBHOOK_SECRET=wsec_...     # HMAC-SHA256 webhook signing secret
+
+# AI Provider
+AI_PROVIDER=openai                     # openai | gemini
+SUMMARY_LANGUAGE=tr                    # tr | en
+SUMMARY_MAX_TOKENS=500
+
+# OpenAI
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-5.4-mini
+
+# Gemini
+GEMINI_API_KEY=...
+GEMINI_MODEL=gemini-pro
+
+# Twilio WhatsApp
+TWILIO_ACCOUNT_SID=...
+TWILIO_AUTH_TOKEN=...
+TWILIO_WHATSAPP_NUMBER=+1234567890
+
+# Unipile (WhatsApp Agent)
+UNIPILE_API_KEY=...                    # Unipile API key
+UNIPILE_DSN=https://api.unipile.com   # Unipile API base URL
+UNIPILE_WEBHOOK_SECRET=...             # Shared secret for webhook validation
+
+# JWT
+JWT_SECRET=...                         # Access token secret
+JWT_REFRESH_SECRET=...                 # Refresh token secret (separate)
+JWT_ACCESS_EXPIRY=15m
+JWT_REFRESH_EXPIRY=7d
+
+# Legacy Admin
+ADMIN_PASSWORD=...                     # Single password for legacy admin panel
+
+# Logging
+LOG_LEVEL=info
+```
+
+---
+
+## 12. Project Structure
+
+```
+elevenlabs-webhook-nodejs/
+├── src/
+│   ├── index.ts                        # Server entry point
+│   ├── app.ts                          # Fastify app setup & plugin registration
+│   ├── config/
+│   │   ├── index.ts                    # Config object
+│   │   ├── env.ts                      # Zod env validation
+│   │   └── database.ts                 # MongoDB connection
+│   ├── plugins/
+│   │   ├── jwt.ts                      # JWT auth plugin
+│   │   ├── rbac.ts                     # Role & feature middleware
+│   │   ├── cors.ts                     # CORS
+│   │   └── rawBody.ts                  # Raw body for webhooks
+│   ├── hooks/
+│   │   └── webhookValidator.ts         # ElevenLabs signature validation
+│   ├── modules/
+│   │   ├── auth/                       # Routes, service, model (User, RefreshToken)
+│   │   ├── users/                      # Routes (CRUD)
+│   │   ├── tenants/                    # Routes, model
+│   │   ├── agents/                     # Routes, model
+│   │   ├── calls/                      # Routes, model
+│   │   ├── surveys/                    # Routes, model
+│   │   ├── campaigns/                  # Routes, service, model
+│   │   ├── billing/                    # Routes, service, model
+│   │   ├── whatsapp/                   # WhatsApp Agent (chat, session, message models + routes)
+│   │   ├── webhooks/                   # ElevenLabs & Unipile webhook routes + services
+│   │   └── admin/                      # SuperAdmin routes
+│   ├── models/                         # Legacy models (Transcription, Summary, WhatsAppRecipient)
+│   ├── routes/
+│   │   ├── health.routes.ts            # Health & WhatsApp status
+│   │   ├── admin.routes.ts             # Legacy admin CRUD
+│   │   └── webhook.routes.ts           # Generic webhook handler
+│   ├── services/
+│   │   ├── whatsapp.service.ts         # Twilio WhatsApp integration
+│   │   ├── unipile.service.ts          # Unipile WhatsApp API client
+│   │   ├── elevenlabs.service.ts       # ElevenLabs API + signed URL
+│   │   ├── whatsapp-agent.service.ts   # Session timers, EL WebSocket, AI responses
+│   │   └── ai/
+│   │       ├── base.ai.ts             # Abstract AI service
+│   │       ├── openai.service.ts      # OpenAI implementation
+│   │       ├── gemini.service.ts      # Gemini implementation
+│   │       └── index.ts               # Factory: createAIService()
+│   ├── templates/
+│   │   ├── index.ts                    # Template exports
+│   │   ├── receptionist.ts            # Receptionist agent template
+│   │   └── survey.ts                  # Survey agent template
+│   ├── types/
+│   │   └── index.ts                    # TypeScript interfaces
+│   └── utils/
+│       └── logger.ts                   # Winston logger
+│
+├── web/
+│   ├── src/
+│   │   ├── main.tsx                    # React entry point
+│   │   ├── App.tsx                     # Router setup
+│   │   ├── index.css                   # Tailwind v4 imports + theme vars
+│   │   ├── contexts/
+│   │   │   └── AuthContext.tsx         # Auth state, login/register/logout, useFeature
+│   │   ├── lib/
+│   │   │   ├── api.ts                 # Axios instance with interceptors
+│   │   │   └── utils.ts               # cn() utility (clsx + tailwind-merge)
+│   │   ├── pages/                     # 17 page components (WhatsApp is single page, two-panel)
+│   │   └── components/
+│   │       ├── ui/                    # shadcn/ui components
+│   │       ├── whatsapp/             # 10 WhatsApp-specific components
+│   │       ├── stat-card.tsx
+│   │       ├── status-badge.tsx
+│   │       ├── page-header.tsx
+│   │       ├── page-loader.tsx
+│   │       ├── empty-state.tsx
+│   │       └── pagination.tsx
+│   ├── components.json                 # shadcn/ui config
+│   ├── vite.config.ts                  # Vite + React + Tailwind + /api proxy
+│   ├── tsconfig.json                   # TS config with @/* path alias
+│   └── package.json
+│
+├── scripts/                            # CLI utilities (add recipient, retrigger, migrate-agent-ref, etc.)
+├── ecosystem.config.js                 # PM2 production config
+├── .env.example                        # Environment template
+├── .env                                # Actual env (gitignored)
+├── tsconfig.json                       # Backend TS config (CommonJS, ES2022)
+└── package.json                        # Backend dependencies & scripts
+```
+
+---
+
+## 13. Deployment
+
+### PM2 Config
+- **App name**: `asistan724-webhook`
+- **Path**: `/var/www/asistan724-webhook-handler/dist/index.js`
+- **Instances**: 1 (single process)
+- **Auto-restart**: enabled
+- **Memory limit**: 500MB
+
+### Build Commands
+```bash
+# Backend
+npm run build    # tsc → dist/ + copy agentPrompts.json
+
+# Frontend
+cd web && npm run build    # tsc --noEmit && vite build
+```
+
+### Dev Commands
+```bash
+npm run dev      # tsx watch mode (backend, port 3005)
+cd web && npm run dev   # vite dev server (port 5173, proxies /api → :3005)
+```
+
+### No CI/CD or Docker configured.
+
+---
+
+## Key Notes
+
+- **No cron jobs needed**: The WhatsApp agent system is fully event-driven (webhooks + in-memory timers). A stuck session sweeper runs every 5 minutes as a safety net. Campaign execution (placing outbound calls) is not yet automated.
+- **Session-based architecture**: WhatsApp chats use a session model (`WhatsAppSession`) to cleanly track conversation boundaries. Messages are scoped to sessions via `session_id`, eliminating fragile backwards-scanning for message boundaries.
+- **Backward-compatible API**: The `enrichChat()` helper derives `mode`, `session_status`, `taken_over_by` from the active session — frontend types/components remain unchanged.
+- **Migration**: Run `npx tsx scripts/migrate-sessions.ts` to migrate existing chat data to the session model. Supports `--dry-run` flag.
+- **Legacy code**: `src/models/` and `src/routes/admin.routes.ts` contain the original pre-SaaS system (single-tenant, password-only auth). Still functional but separate from the multi-tenant module system.
+- **Billing**: Currently tracks call charges only (1.5 TRY/min). No payment gateway integration - billing events are logged but not collected.
+- **Feature flags**: `inbound_agent`, `outbound_campaigns`, `survey_builder`, `whatsapp_notifications`, `whatsapp_agent` - controlled per-tenant by superadmin.
+- **WebSocket reconnection & message buffering**: Production-ready improvements — auto-reconnect with exponential backoff (1.5s, 3s, 6s, max 3 retries) on unexpected WS close, and 20-second message debounce that buffers contact messages before sending combined text to AI.