🤖 WhatsApp Neural Agent - Technical Architecture & Infrastructure Report

011. Fondations & Cadre Stratégique

---

02🏛️ 1. Infrastructure Overview (Docker & Host)

The WhatsApp Agent runs inside an isolated Docker container on the production VPS (`vps164`), structured to handle both Puppeteer browser automation and deep-learning (LLM) API communication.

```mermaid graph TD A[WhatsApp Mobile App] <-->|Signal Sync| B[whatsapp-web.js Client] B <-->|Automation Protocol| C[Headless Chromium Browser] C -->|Reads/Writes Cookies| D[Local Session Storage / .wwebjs_auth] B -->|Triggers event: message| E[Message Handler Logic in index.js] E -->|Prepares Prompt| F[Gemini Multi-Key Rotation Engine] F -->|Key 1 / Key 2| G[Google Gemini API v2.5-flash] G -->|Generates Darija Response| E E -->|Replies via Webpage| B ```

03🔹 Core Components

1. **Container Isolation (`whatsapp_service`)**: Run using a Node.js environment on Debian Bullseye-Slim. This image is pre-packaged with all required libraries for running Chromium inside Linux without a display manager (X11). 2. **Headless Chromium**: Configured to run in sandboxed headless mode, utilizing WebRTC for audio-transcription retrieval and optimized caching. 3. **Internal Express Server**: Listens on port `5000` to serve: - Live browser status `/` and `/qr`. - Dynamic `/qr.png` rendering. - Debug screenshots via `/api/screenshot`. - Internally synced CRM contacts payload via `/api/contacts`.

---

04🔑 2. Multi-Key API Rotation Architecture

Due to the rate limits of the Gemini API Free Tier (requests per minute and per day limits), the agent is equipped with a custom-engineered **Key Rotation and Cool-Down Engine**.

05⚙️ How it Works

1. **Key Array Parsing**: On boot, the system parses all environment variables matching active keys, filtering out any missing/empty variables. ```javascript const GEMINI_API_KEYS = [ process.env.GEMINI_API_KEY, process.env.GEMINI_API_KEY_2, process.env.GEMINI_API_KEY_3 ].filter(Boolean); ``` 2. **Active Key Picker (`getActiveApiKey`)**: - Compares the current timestamp against the cool-down expiration of each key. - Selects the first key that is not under cool-down. - If all keys are currently under cool-down, it selects the key with the shortest remaining cool-down duration to minimize system downtime. 3. **Rotation & Cool-Down Actions (`markKeyExhausted`)**: When a key fails, the cool-down period is set dynamically based on the error code returned by Google APIs: - **429 (Quota Limit)**: The key is put on cool-down for **1 hour** (`3600000ms`) or the duration requested in the `retryDelay` headers. - **403 (Suspended / Blocked Key)**: The key is placed on a **24-hour** cool-down (`86400000ms`), preventing the system from retrying this key during this run. - **Network Timeout / Fetch Failure**: The key is placed on a **5-minute** cool-down (`300000ms`) to allow transient server or network issues to clear.

---

06💾 3. Session Persistence & Recovery (`.wwebjs_auth`)

To prevent requiring the user to scan the QR code whenever the container restarts or rebuilds: 1. The container mounts the `.wwebjs_auth` directory to a persistent volume/folder on the VPS host disk. 2. During initialization, `whatsapp-web.js` checks this folder for browser cookies, session keys, and indexedDB records. 3. **Lock Cleanup**: On startup, a cleanup hook removes active locks (like `DevToolsActivePort`, `SingletonCookie`, `SingletonLock`, `SingletonSocket`) to prevent Chromium from complaining about a "profile already in use" after unexpected restarts. 4. **Auto-Login**: Once locks are cleaned, the Chromium browser reuses the session cache and logs into the WhatsApp account automatically within 10-30 seconds.

---

07❌ The Bug (Key Stall Loop)

Previously, the key rotation loop only checked for error code `429`: ```javascript if (data?.error?.code === 429) { markKeyExhausted(retryMs); continue; // Rotate to next key } ``` If Google returned a `403` error because a key was suspended, the system failed to enter the block. It did not mark the key as exhausted, nor did it call `continue`. Instead, it fell through to the retry delay, kept using the **same suspended key** for all 4 attempts, and eventually threw a fatal `Permission Denied` exception without ever trying the other working keys.

08The Fix (Robust Multi-Error Rotation)

The key rotation logic was rewritten to intercept **any** Google API error or network exception: ```javascript if (data?.error) { const errorCode = data.error.code; const retryDelay = data.error.details?.find(d => d.retryDelay)?.retryDelay; // Rotate key: 24h for 403 (suspended), 1h for 429 (quota), or retryDelay const retryMs = errorCode === 403 ? 86400000 : (retryDelay ? (parseInt(retryDelay) * 1000) : 3600000); markKeyExhausted(retryMs); lastError = data.error; continue; // Immediately try the next key } ``` This ensures that the agent bypasses suspended/expired keys instantly, ensuring continuous, uninterrupted service.

---

09🚀 5. Level Next - Future Enterprise-Grade Improvements

To upgrade the agent's infrastructure to a resilient, enterprise-grade digital asset, the following roadmap features can be integrated:

101️⃣ 📊 Key Health Scoring System (Dynamic Ranking)

- Instead of using a simple binary cool-down state, each API key can be assigned a dynamic **Health Score (0 → 100)**. - The score drops on API errors, high latency, or timeouts, and slowly recovers during periods of successful requests. - The system automatically ranks keys in real-time, routing requests through the highest-scoring keys first.

112️⃣ ⚖️ Load Balancing Engine (Active Distribution)

- Instead of simple sequential failover (only changing keys when a request fails), integrate a **Load Balancer** (e.g., Round Robin or Weighted Latency). - This active distribution scatters API requests across all available active keys simultaneously, reducing the likelihood of hitting rate limits (429) on any single key.

123️⃣ 📡 Observability & Monitoring Dashboard

- Integrate metrics collection endpoints (compatible with **Prometheus / Grafana** or a simple dashboard UI) to monitor: - **Success Rate** per key. - **Error Rate** categorized by code (403, 429, 500). - **API Latency** tracking to identify slow key providers. - **Active Session State** of the Puppeteer client.

134️⃣ 🧠 Multi-LLM AI Router (Provider Agnostic)

- Implement an **AI Router Layer** that abstracts the provider entirely, allowing hot-swapping between **OpenAI (GPT-4o), Anthropic (Claude 3.5), Gemini 2.5**, and open-source models (via Groq/OpenRouter). - The router dynamically chooses the best model depending on the complexity of the task (e.g., cheap/fast models for simple greetings, larger/accurate models for contract estimation).

145️⃣ 🔐 Security Hardening & Automated Key Rotation

- **In-Memory Encryption**: Store API keys encrypted at rest in the environment, decrypting them in-memory only during boot. - **Dynamic Vault Sync**: Integrate with a secret manager (like HashiCorp Vault or Cloud Secret Manager) to automatically fetch, rotate, and validate keys daily without needing to build or recreate the container.