IntelliLead — Enterprise AI-Powered WhatsApp Business Assistant

IntelliLead is a production-ready, highly secure, and modular conversational platform designed to act as an automated customer engagement agent over WhatsApp, integrated with a Next.js administrative dashboard and backend CRM automation triggers (n8n).

---

Technical Architecture

                                  [WhatsApp User]
                                         │
                                         ▼
                                  [Evolution API]
                                         │ (Webhook Payload)
                                         ▼
                                 [Nginx Ingress]
                                         │ (Reverse Proxy & Rate Limit)
                                         ▼
                                 [FastAPI Backend]
                                         │
                    ┌────────────────────┴────────────────────┐
                    ▼                                         ▼
           [AI Safety Engine]                       [Conversation State]
           ├─ Ingress Security Scan                 ├─ Memory (Last 10 chats)
           ├─ Intent Classification                 └─ Handoff State Collector
           ├─ Scope Validation                                │ (Low Similarity)
           ├─ Jailbreak/Injection Filters                     ▼
           │                                          [Human Handoff]
           ├─ [Qdrant RAG Context Retrieval]          ├─ PostgreSQL Tickets
           │  └─ Isolation (Tenant & conversation bounds) ├─ Appointment Scheduler
           │                                          ├─ SMTP Email Alerts
           ├─ AI Generation (Fallback chains)          └─ n8n Workflow Webhooks
           └─ Egress Leakage Validation
                                         │
                                         ▼
                              [WhatsApp Reply Output]

---

Repository Structure

• /src: Next.js 16 (Turbopack + TailwindCSS) administrative web dashboard.
• /backend: FastAPI Python server containing the core AI services, RAG pipelines, database models, and Pytest suites.
• /nginx: Production reverse proxy configuration handling subdomain routes (app., api., n8n.), WebSocket headers, and SSL certificates.
• /monitoring: Scraped container statistics stack utilizing Prometheus metrics and Grafana telemetry dashboards.
• /n8n: Production automation workspace schemas (leads sync, tickets alerts, CRM syncing).
• /scripts: Automated daily PostgreSQL backup and vector snapshot retrieval handlers.
• docker-compose.yml: Master multi-container setup orchestration definition.

---

Core Capabilities

1. AI Safety & response Validation Engine (AISafetyEngine):
   • Mandatory gateway intercepting user input and LLM output.
   • Blocks prompt injection overrides, jailbreaks, and customer data leakages.
   • Strictly enforces RAG confidence boundaries:
     • Similarity score >= 0.80: Proceed with default response.
     • Similarity score 0.60 - 0.79: Proceed with general compliance disclaimer warning.
     • Similarity score < 0.60: Automatically block generation, create ticket and calendar slots, send SMTP alerts, and escalate user to a human operator.
2. Stateful Handoff Flow:
   • Guided conversational collector prompts users step-by-step for ticket descriptions, preferred consultation dates, and time slot configurations.
   • Bypasses RAG retrieval filters on explicit support requests.
   • Pauses AI automation once conversation status transitions to escalated.
3. Multimodal Media Ingestion:
   • Supports voice notes transcription (Whisper fallback) and image vision OCR checks (Gemini/GPT vision) under file upload security validation.
4. Realtime Security Guard Dashboard:
   • Native Next.js 16 security analytics panel serving event alerts tables, Recharts distributions, and aggregate metrics.
   • Binds directly to /api/v1/security/stats and /api/v1/security/events backend API endpoints (configured with JWT auth check overrides for development/admin modes).

---

How to Run the Project

Option A: Running in Docker Mode (Recommended)

Spins up the Next.js web application, FastAPI API, Postgres, Redis, Qdrant, Nginx, Prometheus, Grafana, Node Exporter, and cAdvisor containers automatically:

1. Start all services:

   docker compose up -d --build

2. Apply migrations & seed default records:

   docker compose exec backend alembic upgrade head
   docker compose exec backend sh -c "PYTHONPATH=. python app/database/seed.py"

3. Service Address Layout:
   • Administrative Web App: http://localhost (or http://app.localhost)
   • FastAPI API Swagger Docs: http://localhost:8000/docs (or http://api.localhost/docs)
   • Qdrant Vector Database Dashboard: http://localhost:6333/dashboard
   • Grafana Container Telemetry: http://localhost:3001 (User: admin / Password: admin_monitoring_secure_pwd)

---

Option B: Running Locally (Separate Dev Servers)

1. Spin up local persistent storage:

   docker compose up -d postgres redis qdrant

2. Start the FastAPI Backend:

   cd backend
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   PYTHONPATH=. alembic upgrade head
   PYTHONPATH=. python app/database/seed.py
   PYTHONPATH=. uvicorn app.main:app --reload --port 8000

3. Start the Next.js Frontend:

   # Navigate back to workspace root
   npm install
   npm run dev

   The frontend dashboard will run at http://localhost:3000.

---

Default Login Credentials

Use these credentials to sign into the dashboard panel:

• Email: admin@company.com
• Password: SuperSecureAdminPassword123!

---

Test Verification

Run the offline test suites validating authentication, document uploads, vector indexing, safety gates, and stateful webhooks:

cd backend
source venv/bin/activate
PYTHONPATH=. pytest