elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/06-BAILEYS-MICROSERVICE.md

@@ -0,0 +1,616 @@
+# 06 - Baileys WhatsApp Microservice
+
+> **NOT IN SCOPE FOR LAUNCH.** Baileys microservice is deferred. Meta Business Cloud API is the sole WhatsApp provider at launch. This document is retained as a reference for potential future integration.
+
+> Last updated: 2026-04-02
+
+> The Baileys microservice provides a self-hosted WhatsApp bridge using the
+> @whiskeysockets/baileys library. It runs as a separate Node.js process from the
+> main NestJS application, communicating via Redis pub/sub (target) or HTTP REST (current).
+
+---
+
+## 1. Architecture
+
+### Current Architecture
+
+```
+NestJS :3005
+    |
+    |  HTTP REST calls (UnipileService)
+    |  POST /api/v1/chats/:chatId/messages
+    |  POST /api/v1/chats/:chatId/forward-media
+    |  etc.
+    v
+Baileys Gateway (Express) :3001
+    |
+    |  child_process.fork() IPC
+    |
+    +---> Worker 1 (account-abc)  --- Baileys socket ---> WhatsApp
+    +---> Worker 2 (account-def)  --- Baileys socket ---> WhatsApp
+    +---> Worker N (account-xyz)  --- Baileys socket ---> WhatsApp
+    |
+    v
+MongoDB (shared) -- baileys_auth, baileys_accounts, etc.
+```
+
+### Target Architecture
+
+```
+NestJS :3005
+    |
+    |  Redis pub/sub
+    |  baileys:cmd:{accountId}  (NestJS -> Baileys)
+    |  baileys:evt:{accountId}  (Baileys -> NestJS)
+    |  baileys:req:{reqId}      (request-reply)
+    |
+    v
+Baileys Gateway (Express/Node.js)
+    |
+    |  child_process.fork() IPC (unchanged)
+    |
+    +---> Worker 1 (account-abc)  --- Baileys socket ---> WhatsApp
+    +---> Worker 2 (account-def)  --- Baileys socket ---> WhatsApp
+    +---> Worker N
+    |
+    v
+MongoDB (Baileys-only) -- baileys_auth (encrypted), baileys_accounts
+```
+
+### Key Architectural Decisions
+
+- **Separate process:** Baileys crashes (Signal Protocol issues, WhatsApp bans) must not bring down the main application.
+- **Worker-per-account:** Each WhatsApp account runs in an isolated `child_process.fork()`. This provides memory isolation, independent crash recovery, and supports 10+ concurrent accounts.
+- **Communication change:** HTTP REST (current) is replaced by Redis pub/sub (target) for lower latency and decoupled lifecycle. The gateway subscribes to command channels and publishes events.
+- **Baileys keeps MongoDB:** Auth state and account metadata remain in MongoDB (separate from the main PostgreSQL database). Baileys auth state documents are too frequent and too granular for PostgreSQL.
+
+---
+
+## 2. Redis Pub/Sub Protocol (Target)
+
+### Channel Structure
+
+| Channel Pattern | Direction | Purpose |
+|-----------------|-----------|---------|
+| `baileys:cmd:{accountId}` | NestJS -> Baileys | Commands: send message, connect, disconnect, etc. |
+| `baileys:evt:{accountId}` | Baileys -> NestJS | Events: incoming message, QR code, connection status |
+| `baileys:req:{reqId}` | Baileys -> NestJS | Request-reply responses (for commands that need a return value) |
+
+### Command Messages (NestJS -> Baileys)
+
+Published to `baileys:cmd:{accountId}`:
+
+| Type | Payload | Description | Returns |
+|------|---------|-------------|---------|
+| `connect` | `{ accountId }` | Create new WhatsApp connection, fork worker | QR code or connection status |
+| `reconnect` | `{ accountId }` | Reconnect existing account | QR code or connection status |
+| `disconnect` | `{ accountId }` | Disconnect and delete account | -- |
+| `status` | `{ accountId }` | Get current connection status | Status object |
+| `send` | `{ chatId, text, reqId }` | Send text message | `{ message_id }` |
+| `start_chat` | `{ phone, text, reqId }` | Start new chat with a phone number | `{ chat_id, message_id }` |
+| `send_image` | `{ chatId, imageBase64, caption, reqId }` | Send base64 image | `{ message_id }` |
+| `forward_media` | `{ messageId, toPhone, caption, reqId }` | Forward cached media to another phone | `{ message_id }` |
+| `download_audio` | `{ messageId, reqId }` | Download audio from cached voice message | `{ audio_base64 }` |
+
+### Event Messages (Baileys -> NestJS)
+
+Published to `baileys:evt:{accountId}`:
+
+| Type | Payload | Description |
+|------|---------|-------------|
+| `qr` | `{ qr }` | QR code string for scanning (raw, not data URL) |
+| `connected` | `{ phone }` | WhatsApp connection established successfully |
+| `disconnected` | `{ reason, statusCode? }` | Unexpected disconnect (network, auth issue) |
+| `logged_out` | -- | Session ended by user or WhatsApp (requires re-scan) |
+| `message` | `{ payload }` | Incoming WhatsApp message in normalized webhook format |
+| `reply` | `{ reqId, data?, error? }` | Response to a command that included a `reqId` |
+
+### Request-Reply Pattern
+
+For commands that need a response (send, forward_media, download_audio):
+
+1. NestJS generates a `reqId` (UUID) and includes it in the command
+2. NestJS subscribes to `baileys:req:{reqId}` (or uses a shared reply channel with message filtering)
+3. Baileys publishes the result to `baileys:req:{reqId}`
+4. NestJS resolves the pending promise with the result
+5. Timeout: 30 seconds, then reject with error
+
+---
+
+## 3. Worker IPC Protocol (Unchanged)
+
+The internal communication between the gateway process and worker processes uses Node.js IPC (`process.send` / `process.on('message')`). This protocol is unchanged in the migration.
+
+### Gateway -> Worker Messages
+
+| Type | Payload | Description |
+|------|---------|-------------|
+| `init` | `{ accountId, authDir, mongodbUri, mediaForwardTo }` | Initialize worker with account config |
+| `send` | `{ chatId, text, reqId }` | Send text message (chatId = raw JID) |
+| `start_chat` | `{ phone, text, reqId }` | Start chat with phone number |
+| `send_image` | `{ chatId, imageBase64, caption, reqId }` | Send image |
+| `forward_media` | `{ messageId, toPhone, caption, reqId }` | Forward cached media |
+| `download_audio` | `{ messageId, reqId }` | Download voice message audio |
+| `disconnect` | -- | Graceful disconnect and logout |
+| `shutdown` | -- | Graceful shutdown (save state, close socket) |
+
+### Worker -> Gateway Messages
+
+| Type | Payload | Description |
+|------|---------|-------------|
+| `qr` | `{ qr }` | QR code for WhatsApp Web scanning |
+| `connected` | `{ phone }` | Successfully connected, phone number confirmed |
+| `disconnected` | `{ reason, statusCode? }` | Connection lost |
+| `logged_out` | -- | Session terminated (account must re-authenticate) |
+| `status` | `{ status }` | Current status update |
+| `message` | `{ payload }` | Normalized incoming message (Unipile-compatible format) |
+| `reply` | `{ reqId, data?, error? }` | Response to a request |
+| `ready` | -- | Worker initialized and ready to receive commands |
+
+### Message Payload Format
+
+The `message` type carries a payload normalized to match the Unipile webhook format. This ensures the NestJS webhook handler can process messages from both Baileys and Unipile/Meta identically.
+
+```typescript
+{
+  account_id: string,           // Baileys account UUID
+  account_type: 'WHATSAPP',
+  event: 'message_received',
+  chat_id: string,              // Composite: '{accountId}:{jid}'
+  message_id: string,           // Baileys message key ID
+  message: string,              // Extracted text or media label
+  content_type: string,         // e.g., 'conversation', 'imageMessage', 'audioMessage'
+  timestamp: string,            // ISO 8601
+  is_sender: boolean,           // true if sent by the clinic account
+  sender: {
+    attendee_id: string,
+    attendee_name: string,
+    attendee_provider_id: string,
+    attendee_specifics: { phone_number: string },
+  },
+  attendees: [...],             // Contact info array
+  account_info: { type: 'WHATSAPP', phone_number: string },
+  ad_context?: { ... } | null,  // Ad attribution from contextInfo
+  quoted_text?: string | null,   // Quoted message text (for reply detection)
+}
+```
+
+---
+
+## 4. Auth State Security
+
+### Current Problem: Plain Text Credentials
+
+Baileys stores WhatsApp Signal Protocol credentials in the `baileys_auth` MongoDB collection as **unencrypted JSON**. Each account has 20-50 documents:
+
+| Document Type | Contains | Risk If Exposed |
+|---------------|----------|-----------------|
+| `creds.json` | Curve25519 identity keypair, signed pre-key (private), advance secret key, noise key, registration ID | **Full account takeover** -- attacker can impersonate the WhatsApp session |
+| `pre-key-{ID}.json` | Curve25519 pre-key pairs (forward secrecy) | Decrypt past messages |
+| `sender-key-{ID}.json` | Group encryption keys | Read group messages |
+| `app-state-sync-key-{ID}.json` | History sync encryption keys | Decrypt message history |
+
+Documents are serialized with `BufferJSON.replacer` -- that is **serialization, not encryption**. Anyone with MongoDB read access can extract full key material.
+
+### Target: AES-256-GCM Encryption Per Account
+
+#### Encryption Flow
+
+```
+Write path:
+  auth data (JSON) --> JSON.stringify(data, BufferJSON.replacer)
+                   --> AES-256-GCM encrypt(derivedKey, iv, plaintext)
+                   --> base64(iv + authTag + ciphertext)
+                   --> store in MongoDB { data: "base64...", encrypted: true }
+
+Read path:
+  MongoDB { data: "base64..." } --> base64 decode
+                                --> extract iv (12 bytes) + authTag (16 bytes) + ciphertext
+                                --> AES-256-GCM decrypt(derivedKey, iv, ciphertext, authTag)
+                                --> JSON.parse(plaintext, BufferJSON.reviver)
+                                --> auth data (JSON)
+```
+
+#### Key Derivation (HKDF)
+
+Each account gets a unique encryption key derived from a master key:
+
+```
+Master key:     BAILEYS_AUTH_ENCRYPTION_KEY (32-byte hex from env)
+Per-account:    HKDF(masterKey, accountId) --> unique AES-256 key
+
+Benefit:        Compromise of one account's key material in memory
+                does not expose other accounts' auth state.
+```
+
+```typescript
+function deriveKey(masterKeyHex: string, accountId: string): Buffer {
+  const masterKey = Buffer.from(masterKeyHex, 'hex');
+  // HKDF: extract-then-expand
+  return hkdf(masterKey, 32, { salt: accountId, info: 'baileys-auth' });
+}
+
+function encryptAuthData(accountId: string, data: any): string {
+  const key = deriveKey(ENCRYPTION_KEY, accountId);
+  const iv = randomBytes(12);  // AES-256-GCM nonce
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const plaintext = JSON.stringify(data, BufferJSON.replacer);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return Buffer.concat([iv, authTag, encrypted]).toString('base64');
+}
+
+function decryptAuthData(accountId: string, encryptedBase64: string): any {
+  const key = deriveKey(ENCRYPTION_KEY, accountId);
+  const buf = Buffer.from(encryptedBase64, 'base64');
+  const iv = buf.subarray(0, 12);
+  const authTag = buf.subarray(12, 28);
+  const ciphertext = buf.subarray(28);
+  const decipher = createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(authTag);
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+  return JSON.parse(plaintext, BufferJSON.reviver);
+}
+```
+
+#### MongoDB Document After Encryption
+
+```json
+{
+  "_id": "account-uuid:creds.json",
+  "accountId": "account-uuid",
+  "filename": "creds.json",
+  "data": "base64-encrypted-blob...",
+  "encrypted": true,
+  "updatedAt": "2026-03-29T..."
+}
+```
+
+The `encrypted: true` flag enables a migration path: the system can detect unencrypted documents and refuse to read them after migration is complete.
+
+#### Key Management
+
+| Concern | Solution |
+|---------|----------|
+| Master key storage | `BAILEYS_AUTH_ENCRYPTION_KEY` in env var -- never in code or DB |
+| Per-account isolation | HKDF derives unique key per `accountId` -- compromise of one does not expose others |
+| Key rotation | New master key -> re-encrypt all documents in a migration script. Old key kept temporarily for rollback |
+| Docker deployment | Pass via `environment` or Docker secrets -- not baked into image |
+| Backup safety | Database dumps are useless without the master key |
+
+#### Migration Plan
+
+| Step | Action | Location |
+|------|--------|----------|
+| 1 | Add `BAILEYS_AUTH_ENCRYPTION_KEY` env var | Baileys `.env` |
+| 2 | Create `encrypt/decrypt` helpers with HKDF | `baileys/src/utils/crypto.js` |
+| 3 | Wrap `useMongoDBAuthState()` -- encrypt on write, decrypt on read | `baileys/src/utils/use-mongodb-auth-state.js` |
+| 4 | One-time migration script: read all plain docs -> encrypt -> rewrite | Standalone script |
+| 5 | Add `encrypted: true` flag -- reject plain reads after migration | Safety check |
+| 6 | Encrypt file fallback (same AES-256-GCM) | `baileys/src/utils/use-file-auth-state.js` |
+
+---
+
+## 5. QR Code Flow
+
+### Connection Sequence
+
+```
+Admin UI         NestJS API          Baileys Gateway        Worker          WhatsApp
+   |                 |                     |                   |                |
+   |-- Connect -->   |                     |                   |                |
+   |  (POST          |                     |                   |                |
+   |   /connect)     |                     |                   |                |
+   |                 |--- cmd: connect --->|                   |                |
+   |                 |                     |                   |                |
+   |                 |                     |-- fork worker --->|                |
+   |                 |                     |                   |                |
+   |                 |                     |-- IPC: init ----->|                |
+   |                 |                     |                   |                |
+   |                 |                     |                   |-- Baileys      |
+   |                 |                     |                   |   connect ---->|
+   |                 |                     |                   |                |
+   |                 |                     |                   |<-- QR data ----|
+   |                 |                     |                   |                |
+   |                 |                     |<-- IPC: qr -------|                |
+   |                 |                     |                   |                |
+   |                 |<-- evt: qr ---------|                   |                |
+   |                 |   (raw QR string)   |                   |                |
+   |                 |                     |                   |                |
+   |<-- QR code -----|                     |                   |                |
+   |  (checkpoint.   |                     |                   |                |
+   |   qrcode)       |                     |                   |                |
+   |                 |                     |                   |                |
+   | User scans QR   |                     |                   |                |
+   | on their phone  |                     |                   |                |
+   |                 |                     |                   |                |
+   |                 |                     |                   |<-- connected --|
+   |                 |                     |                   |                |
+   |                 |                     |<-- IPC: connected-|                |
+   |                 |                     |   { phone }       |                |
+   |                 |                     |                   |                |
+   |                 |<-- evt: connected --|                   |                |
+   |                 |                     |                   |                |
+   |<-- status ok ---|                     |                   |                |
+```
+
+### QR Code Format
+
+The QR code is returned as a **raw string** in `checkpoint.qrcode`. The frontend renders it using `QRCodeSVG` from the `qrcode.react` library. It is NOT a data URL or image -- it is the raw data that the QR library encodes.
+
+### Timeout
+
+- **QR wait timeout:** 30 seconds (`config.qrTimeoutMs`)
+- If the user does not scan in time, the API returns without a QR and the admin must retry
+- **Baileys connection timeout:** 60 seconds (`config.connectTimeoutMs`)
+
+---
+
+## 6. Connection Management
+
+### Auto-Restart
+
+When a worker process exits unexpectedly:
+
+| Condition | Action |
+|-----------|--------|
+| `status === 'logged_out'` | Do NOT restart -- user logged out or was banned |
+| `status === 'conflict'` | Do NOT restart -- another session is active on this account |
+| Account deleted | Do NOT restart -- clean up worker entry |
+| `restartCount > 5` | Give up -- mark account as `'failed'` |
+| Otherwise | Restart with exponential backoff |
+
+### Restart Backoff
+
+```
+delay = workerRestartDelayMs * restartCount
+      = 3000ms * attempt
+
+Attempt 1: 3s
+Attempt 2: 6s
+Attempt 3: 9s
+Attempt 4: 12s
+Attempt 5: 15s
+Attempt 6: Give up (max 5 restarts)
+```
+
+The `restartCount` resets to 0 on a successful connection (`connected` message received).
+
+### Timeout Values
+
+| Timeout | Value | Purpose |
+|---------|-------|---------|
+| QR wait | 30s | How long `createAccount` waits for QR before responding |
+| Baileys connect | 60s | Baileys internal connection timeout |
+| Worker restart delay | 3s * attempt | Backoff between restart attempts |
+| Max restarts | 5 | Consecutive failures before giving up |
+| Worker request timeout | 30s | How long gateway waits for worker to respond to a command |
+| Worker shutdown grace | 3s | How long to wait for graceful shutdown before `kill()` |
+
+### Account Restoration on Startup
+
+On gateway startup, `restoreAll()`:
+
+1. Kill any orphaned worker processes from a previous run (`pkill -f worker.js`)
+2. Load all accounts from MongoDB
+3. Filter to `connected` or `disconnected` status (skip `logged_out`, `failed`)
+4. Fork a worker for each restorable account
+5. Workers automatically reconnect using stored auth state
+
+### Graceful Shutdown
+
+`shutdownAll()` sends `{ type: 'shutdown' }` IPC to all workers, waits up to 3 seconds per worker for exit, then force-kills any remaining processes.
+
+---
+
+## 7. Media Cache
+
+### Purpose
+
+Baileys' `downloadMediaMessage()` requires the **original message object** (containing encryption keys, media URL, etc.). The worker caches incoming media messages in memory so they can be re-downloaded later for forwarding to the doctor.
+
+### Implementation
+
+```typescript
+// In worker.js
+const messageCache = new Map();
+// Key:   message ID (string)
+// Value: { msg: BaileysMessage, contentType: string, timestamp: number }
+
+const MESSAGE_CACHE_TTL_MS = 60 * 60 * 1000;  // 60 minutes
+```
+
+### Lifecycle
+
+1. **Cache on receive:** When `messages.upsert` fires with a media message, the full Baileys message object is stored in `messageCache`
+2. **Forward on demand:** When `forward_media` IPC is received, look up the message, call `downloadMediaMessage()`, send the buffer to the target phone
+3. **TTL cleanup:** Every 5 minutes, entries older than 60 minutes are evicted
+4. **Cache miss:** If the message is not in cache (expired or worker restarted), the forward fails with an error
+
+### Target Migration
+
+In the NestJS rewrite, media is stored in MinIO on receipt (not just cached in memory). This eliminates the TTL limitation and survives worker restarts. The `forward_media` command reads from MinIO instead of the worker's in-memory cache.
+
+---
+
+## 8. MongoDB Collections (Baileys-Specific)
+
+These collections are used exclusively by the Baileys microservice. They remain in MongoDB even after the main application migrates to PostgreSQL.
+
+| Collection | Purpose | TTL | Key Fields |
+|------------|---------|-----|------------|
+| `baileys_auth` | Signal Protocol credentials and keys | None | `accountId`, `filename`, `data`, `encrypted` |
+| `baileys_accounts` | Account metadata (status, phone, timestamps) | None | `accountId`, `status`, `phone`, `createdAt` |
+| `baileys_webhooks` | Registered webhook URLs and secrets | None | `url`, `secret`, `events` |
+| `baileys_message_log` | Message event log (dispatched, filtered, errors) | 7 days | `accountId`, `action`, `messageId`, `timestamp` |
+| `baileys_raw_messages` | Raw Baileys message objects (debug) | 7 days | `accountId`, `remoteJid`, `messageId`, `raw` |
+
+### baileys_auth
+
+Stores one document per auth state file per account:
+- `_id`: `{accountId}:{filename}` (e.g., `abc-123:creds.json`)
+- `accountId`: account UUID
+- `filename`: auth state file name (e.g., `creds.json`, `pre-key-1.json`)
+- `data`: serialized JSON (currently plain, target: encrypted base64)
+- `encrypted`: boolean flag (target: true after migration)
+
+The `useMongoDBAuthState()` utility provides a Baileys-compatible auth state interface backed by these MongoDB documents. It implements `saveCreds()`, `get()`, `set()`, `remove()`, and `keys()`.
+
+### baileys_accounts
+
+One document per WhatsApp account:
+- `accountId`: UUID
+- `status`: `creating` | `connected` | `disconnected` | `logged_out` | `conflict` | `failed`
+- `phone`: connected phone number (null until connected)
+- `createdAt`: creation timestamp
+
+### baileys_webhooks
+
+Webhook registrations for dispatching incoming messages to the main application:
+- `url`: webhook endpoint (e.g., `http://nestjs:3005/webhooks/unipile`)
+- `secret`: shared secret sent as `x-unipile-secret` header
+- `events`: array of event types to receive
+
+### Message Log and Raw Messages
+
+Debug/operational logs with 7-day TTL (MongoDB TTL index):
+- `baileys_message_log`: structured log of message events (dispatched, filtered, send_failed, worker_exit, etc.)
+- `baileys_raw_messages`: full Baileys message objects for debugging protocol issues
+
+---
+
+## 9. Composite Chat ID
+
+Baileys uses JIDs (Jabber IDs) as chat identifiers (e.g., `905551234567@s.whatsapp.net`). Since the system supports multiple WhatsApp accounts, a composite chat ID is used:
+
+```
+Format:    {accountId}:{jid}
+Example:   abc-123-def:905551234567@s.whatsapp.net
+```
+
+### Why Composite
+
+- Multiple accounts may chat with the same phone number
+- The `accountId` prefix routes commands to the correct worker
+- The NestJS side treats the composite ID as an opaque string (same as Unipile's chat IDs)
+
+### Parsing
+
+```typescript
+function buildChatId(accountId, jid) {
+  return `${accountId}:${jid}`;
+}
+
+function parseChatId(chatId) {
+  const sep = chatId.indexOf(':');
+  return {
+    accountId: chatId.slice(0, sep),
+    jid: chatId.slice(sep + 1),
+  };
+}
+```
+
+---
+
+## 10. Message Filtering
+
+The worker filters out non-conversational messages before dispatching to the gateway. These are filtered:
+
+| Filter | Check | Reason |
+|--------|-------|--------|
+| Broadcast messages | `isJidBroadcast(jid)` | Not real conversations |
+| Group messages | `isJidGroup(jid)` | Only 1:1 chats supported |
+| LID users | `isLidUser(jid)` | Internal WhatsApp identifiers |
+| Protocol messages | `messageStubType` present | System events (group changes, etc.) |
+| Status broadcasts | `jid === 'status@broadcast'` | WhatsApp Status stories |
+| Own messages (partial) | `key.fromMe === true` | Echoes are passed through for dedup but flagged as `is_sender: true` |
+
+### Content Type Detection
+
+The worker uses `getContentType(message)` from Baileys to identify the message type:
+- `conversation` -- plain text
+- `extendedTextMessage` -- text with URL preview or reply
+- `imageMessage` -- photo
+- `videoMessage` -- video
+- `audioMessage` -- voice message
+- `documentMessage` -- file attachment
+- `stickerMessage` -- sticker
+- `contactMessage` -- shared contact
+- `locationMessage` -- GPS location
+
+### Text Extraction
+
+For text messages: direct text field. For media messages: a Turkish-language label is generated (e.g., `"[Kullanici fotograf gonderdi]"`, `"[Kullanici ses mesaji gonderdi]"`). These labels pass through to the AI agent so it knows media was shared even though text-only mode is used.
+
+---
+
+## 11. Webhook Dispatching
+
+When a worker sends a `message` event, the gateway dispatches it to all registered webhooks:
+
+1. Look up all webhooks from `baileys_webhooks` collection
+2. For each webhook: POST the normalized payload with `x-unipile-secret` header
+3. Retry on failure: 3 attempts with exponential backoff (`1s * 2^attempt`)
+4. Auto-registration: if `WEBHOOK_AUTO_URL` env var is set, a webhook is automatically created on startup
+
+The webhook format matches the Unipile format, so the NestJS webhook handler does not need to distinguish between Baileys and Unipile origins.
+
+---
+
+## 12. Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3001` | HTTP server port |
+| `BAILEYS_API_KEY` | -- | API key for REST endpoint authentication |
+| `DATA_DIR` | `./data` | Directory for file-based auth state fallback |
+| `LOG_LEVEL` | `info` | Pino log level |
+| `MONGODB_URI` | -- | MongoDB connection string |
+| `MONGO_USER` | -- | MongoDB username (injected into URI if no credentials present) |
+| `MONGO_PASS` | -- | MongoDB password |
+| `MEDIA_FORWARD_TO` | -- | Dev: auto-forward media messages to this phone |
+| `WEBHOOK_AUTO_URL` | -- | Auto-register this webhook URL on startup |
+| `WEBHOOK_AUTO_SECRET` | -- | Secret for auto-registered webhook |
+| `BAILEYS_AUTH_ENCRYPTION_KEY` | -- | **(Target)** 32-byte hex for auth state encryption |
+
+### Timeout Configuration
+
+| Config Key | Value | Description |
+|------------|-------|-------------|
+| `qrTimeoutMs` | 30,000 | Max wait for QR code before responding |
+| `connectTimeoutMs` | 60,000 | Baileys connection timeout |
+| `workerRestartDelayMs` | 3,000 | Base delay between worker restart attempts |
+| `workerMaxRestarts` | 5 | Max consecutive restart attempts before giving up |
+| `webhookRetries` | 3 | Max webhook delivery retry attempts |
+| `webhookRetryBaseMs` | 1,000 | Base delay for webhook retry backoff |
+
+---
+
+## 13. File Structure
+
+```
+baileys/
+  server.js                          # Express app entry point
+  worker.js                          # Baileys worker process (forked per account)
+  package.json
+  .env
+  data/                              # File-based auth state fallback (per-account dirs)
+  src/
+    config.js                        # Configuration with MongoDB URI builder
+    middleware/
+      api-key.js                     # API key validation middleware
+    routes/
+      accounts.js                    # Account CRUD: create, reconnect, status, disconnect
+      chats.js                       # Chat operations: send, forward-media, send-image, download-audio, start-chat
+      webhooks.js                    # Webhook registration CRUD
+    services/
+      account-store.js               # MongoDB account persistence + file system helpers
+      webhook-dispatcher.js          # HTTP webhook delivery with retry
+      worker-manager.js              # Worker lifecycle: fork, IPC, auto-restart, request-reply
+    utils/
+      jid.js                         # JID-to-phone conversion, text extraction, media labels
+      logger.js                      # Pino logger configuration
+      use-mongodb-auth-state.js      # Baileys auth state adapter for MongoDB
+```