Skip to content

AhmadFaour9/NexusAI-Intelligent-Customer-Experience-Platform

BranchesTags

Repository files navigation

🤖 NexusAI: Intelligent Customer Experience Platform

Next.js React TypeScript Google Cloud Gemini Pro Docker Cloud Run

Enterprise-grade AI agent handling support, orders, and analytics at scale.

🌐 Live Demo · 📊 Admin Portal · 🐛 Report Bug · 💡 Request Feature

📖 Overview

NexusAI is a cutting-edge Support Automation Platform designed for high-volume e-commerce businesses. It goes beyond simple chatbots by integrating deeply with your core business systems (Order Management, CRM, Knowledge Base) to resolve 60-80% of inquiries automatically.

When human intervention is needed, NexusAI provides a seamless "Smart Handoff" experience, categorizing tickets by priority and giving agents full context.

🚀 Live Deployment

The platform is currently deployed and operational on Google Cloud Run:

Service URL
Customer Chatbot chatbot-frontend-aljdeea7va-uc.a.run.app
Admin Dashboard chatbot-frontend-aljdeea7va-uc.a.run.app/admin/dashboard
Live Chat Panel chatbot-frontend-aljdeea7va-uc.a.run.app/admin/chat
Backend API chatbot-backend-369742266618.us-central1.run.app

Default Admin Credentials:

  • Email: admin@example.com
  • Password: admin123

✨ Key Features

🛒 AI-Powered Customer Assistant

  • Intent Resolution: Powered by Gemini 2.0 Flash, it understands context, sentiment, and complex queries.
  • RAG (Retrieval-Augmented Generation): Falls back to a knowledge base for unstructured questions.
  • Interactive Tools: Can look up orders, check stock, and process refunds in real-time.
  • Multilingual Fluency: Native support for English and Arabic, with automatic RTL layout switching.

🧠 Intelligent Priority System

  • Semantic Classification: Uses LLMs to analyze ticket severity (not just keywords).
  • Auto-Triage:
    • 🔴 High: Security, Fraud, Legal (Immediate Agent Alert)
    • 🟡 Medium: Refunds, Payments, Order Issues
    • 🟢 Low: General Inquiries, Feedback
  • Smart Queuing: High-priority tickets automatically jump to the top of the agent's queue.

⚡ Live Operations Dashboard

  • Real-time Oversight: Watch AI conversations happen in real-time via Firestore sync.
  • Agent Takeover: Jump into any conversation instantly from the Live Chat panel.
  • Data Analytics: BigQuery-backed insights into user intent, peak times, and resolution rates.
  • Staff Management: Full RBAC with privilege-based access control.

📊 Analytics & Reporting

  • Total Requests: Track all incoming chat requests.
  • Average Latency: Monitor AI response times.
  • Error Rate: Keep tabs on system health.
  • Requests Per Day: Visualize traffic trends.
  • Top Intents: See what customers are asking about most.

🧪 Testing & Validation

  • Prompt Validation (stage2_validate.py): Dedicated script to validate text classification prompts and ensure AI model output quality before deployment.
  • Automated Testing (stage3_test.py): comprehensive test suite to verify system integrity, API endpoints, and data flow correctness.

🔄 Validation & Testing Workflow

graph LR
    A[Input Data] --> B[Stage 2: Validate]
    B -->|Check Prompts| C{Prompt Valid?}
    C -->|Yes| D[Stage 3: Test]
    C -->|No| E[Refine Prompt]
    E --> B
    D -->|Run Tests| F{Tests Pass?}
    F -->|Yes| G[Deploy / Ready]
    F -->|No| H[Debug & Fix]
    H --> D
Loading

🏗️ System Architecture

NexusAI uses a robust microservices architecture managed on Google Cloud Run.

┌─────────────────────────────────────────────────────────────────────────────┐
│                              PRESENTATION LAYER                              │
│  ┌───────────────────────┐         ┌───────────────────────────────────────┐ │
│  │    Customer Portal    │         │            Admin Dashboard            │ │
│  │    (Next.js 14)       │         │   (Dashboard, Chat, Cases, Orders)   │ │
│  └───────────┬───────────┘         └───────────────────┬───────────────────┘ │
└──────────────┼─────────────────────────────────────────┼────────────────────┘
               │                                         │
               │  HTTPS + HTTP-only Cookies (JWT)        │
               ▼                                         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                               BACKEND LAYER                                  │
│                          (Node.js / Express)                                 │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│  │ Auth Module  │ │ Session Mgr  │ │ Dialog Engine│ │  Live Chat Module   │ │
│  │  (JWT/RBAC)  │ │  (In-Memory) │ │   (Flows)    │ │  (Firestore Sync)   │ │
│  └──────────────┘ └──────────────┘ └──────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
               │                      │                      │
               ▼                      ▼                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          INTELLIGENCE & DATA LAYER                           │
│  ┌───────────────────┐  ┌───────────────────┐  ┌──────────────────────────┐ │
│  │   Vertex AI API   │  │     Firestore     │  │        BigQuery          │ │
│  │ (Gemini 2.0 Flash)│  │ (active_sessions) │  │   (intent_analytics)     │ │
│  │                   │  │      (staff)      │  │    - cases               │ │
│  │   - Classification│  │     (orders)      │  │    - human_feedback      │ │
│  │   - RAG Generation│  │                   │  │                          │ │
│  └───────────────────┘  └───────────────────┘  └──────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

Data Flow

User sends message
        │
        ├──────────────────────────────────────────────────────────┐
        ▼                                                          ▼
┌───────────────────────────────┐              ┌───────────────────────────────┐
│  Firestore (active_sessions)  │              │      BigQuery (cases)         │
│  Real-time chat sync for      │              │  Analytics & metrics for      │
│  agents in Live Chat panel    │              │  Admin Dashboard              │
└───────────────────────────────┘              └───────────────────────────────┘

🛠️ Technology Stack

Component Technology Description
Frontend Next.js 14, React, Tailwind CSS SEO-optimized, responsive (Mobile/Desktop), glassmorphic UI.
Backend Node.js, Express RESTful API, WebSocket handling, Middleware architecture.
AI / ML Gemini 2.0 Flash, Vertex AI LLM for intent classification and RAG generation.
Database Firestore, BigQuery Real-time session sync (Firestore) + Long-term analytics (BigQuery).
Authentication JWT + HTTP-only Cookies Secure, cross-site cookie support with SameSite=None.
DevOps Docker, Cloud Run Containerized stateless deployment, auto-scaling to zero.

📁 Project Structure

chatbot-platform/
├── backend/
│   ├── src/
│   │   ├── index.js                 # Express server entry point
│   │   ├── lib/
│   │   │   └── firestore.js         # Firestore client initialization
│   │   └── modules/
│   │       ├── auth/                # JWT authentication & RBAC
│   │       ├── bigquery-client/     # BigQuery analytics logging
│   │       ├── dialogue-manager/    # Conversation flow engine
│   │       ├── intent-client/       # Gemini-based intent classification
│   │       ├── live-chat/           # Real-time Firestore chat sync
│   │       ├── orders/              # Order management (Firestore)
│   │       ├── rag/                 # Retrieval-Augmented Generation
│   │       ├── session-manager/     # In-memory session state
│   │       └── translations/        # i18n (English/Arabic)
│   ├── Dockerfile
│   └── package.json
│
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.tsx             # Customer chatbot UI
│   │   │   ├── admin/
│   │   │   │   ├── dashboard/       # Analytics Dashboard
│   │   │   │   ├── chat/            # Live Chat Panel
│   │   │   │   ├── cases/           # Closed Session History
│   │   │   │   ├── orders/          # Order Management
│   │   │   │   ├── staff/           # Staff Management (RBAC)
│   │   │   │   └── login/           # Admin Login
│   │   │   └── employee/
│   │   │       └── chat/            # Employee Chat View
│   │   ├── components/              # Reusable UI components
│   │   ├── lib/
│   │   │   └── api.ts               # API client with cookie support
│   │   └── locales/                 # i18n translation files
│   ├── Dockerfile
│   └── package.json
│
└── README.md

🔑 Environment Variables

Backend (backend/.env)

# Google Cloud
PROJECT_ID=your-gcp-project-id
LOCATION=us-central1
BUCKET=your-gcs-bucket

# BigQuery
BQ_ENABLED=1
BQ_DATASET=intent_analytics
BQ_TABLE=request_logs

# Authentication
JWT_SECRET=your-super-secret-key
JWT_EXPIRES_IN=24h
ADMIN_PASSWORD_HASH=$2a$10$...  # bcrypt hash of admin password

# Frontend URL (for CORS)
FRONTEND_URL=https://your-frontend-url.run.app
NODE_ENV=production

Frontend (frontend/.env.local)

NEXT_PUBLIC_API_URL=https://your-backend-url.run.app

🚀 Deployment

Deploy to Google Cloud Run

Backend:

cd backend
gcloud run deploy chatbot-backend \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars PROJECT_ID=your-project-id \
  --set-env-vars LOCATION=us-central1 \
  --set-env-vars BQ_ENABLED=1 \
  --set-env-vars BQ_DATASET=intent_analytics \
  --set-env-vars FRONTEND_URL=https://your-frontend.run.app \
  --set-env-vars NODE_ENV=production

Frontend:

cd frontend
gcloud run deploy chatbot-frontend \
  --source . \
  --region us-central1 \
  --allow-unauthenticated

📦 Getting Started (Local Development)

Prerequisites

  • Node.js 18+
  • Google Cloud Platform Account (Vertex AI, Firestore, BigQuery enabled)
  • gcloud CLI authenticated

Installation

  1. Clone the Repository

    git clone https://github.com/ahmadfaour/nexus-ai.git
cd nexus-ai

  2. Backend Configuration

    cd backend
npm install
# Create .env file with your credentials
cp .env.example .env
npm run dev

  3. Frontend Configuration

    cd frontend
npm install
npm run dev

  4. Access the Platform

    • Customer Portal: http://localhost:3000
    • Admin Dashboard: http://localhost:3000/admin/dashboard
    • Live Chat: http://localhost:3000/admin/chat

🔒 Security & Privacy

  • Role-Based Access Control (RBAC): Strict separation between Users, Agents (employee), and Admins (admin).
  • Privilege System: Granular permissions (p_chat_live, p_staff_manage, p_admin_dashboard, etc.).
  • HTTP-Only Cookies: JWT tokens stored in secure, HTTP-only cookies to prevent XSS.
  • Cross-Site Cookie Support: SameSite=None and Secure=true for Cloud Run domains.
  • Data Encryption: All data in transit (TLS) and at rest (Firestore/BigQuery Encryption) is secured.
  • Compliance: Designed with GDPR/CCPA principles (Right to be Forgotten supported).

🚀 Vision & Roadmap

We are constantly evolving. Here is our plan for the next releases:

  • Omnichannel Support: Integration with WhatsApp Business API and Messenger.
  • Voice & Audio: Speech-to-Text (STT) for voice notes and Text-to-Speech (TTS) usage.
  • Multimodal Inputs: Allow users to upload images of damaged products for auto-refund evaluation.
  • Proactive Engagement: AI-driven outreach for delayed orders or abandoned carts.
  • Enterprise SSO: SAML/OIDC integration for staff access.
  • Advanced Analytics: Sentiment analysis, churn prediction, and customer satisfaction scoring.

🤝 Contact & Support

Ahmad Faour
Lead AI Architect

LinkedIn GitHub

Made with ❤️ for the future of commerce.

About

NexusAI is a cutting-edge Support Automation Platform designed for high-volume e-commerce businesses. It goes beyond simple chatbots by integrating deeply with your core business systems (Order Management, CRM, Knowledge Base) to resolve 60-80% of inquiries automatically.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages