AI RAG Assistant Chatbot

My Personal AI Assistant Project - Lumina 👨🏻‍💻

David Nguyen's Personal AI Assistant - Lumina is a full-stack web application that allows users to ask questions about David Nguyen, as well as any other topics, and receive instant, personalized responses powered by state‑of‑the‑art AI & RAG. Users can log in to save their conversation history or continue as guests. The app uses modern technologies and provides a sleek, responsive user interface with intuitive UX and lots of animations. 🚀

Table of Contents

• [Live App](#live-app)
• [Key Technologies](#key-technologies)
• [Features](#features)
• [Architecture](#architecture)
• [High-Level System Architecture](#high-level-system-architecture)
• [RAG Flow](#rag-retrieval-augmented-generation-flow)
• [Data Flow Architecture](#data-flow-architecture)
• [Detailed Architecture Documentation](#detailed-architecture-documentation)
• [Setup & Installation](#setup--installation)
• [Backend Setup](#backend-setup)
• [Frontend Setup](#frontend-setup)
• [AI/ML Setup](#aiml-setup)
• [Knowledge Management](#knowledge-management)
• [Deployment](#deployment)
• [Current Deployment (Vercel)](#current-deployment-vercel)
• [Docker Deployment](#docker-deployment)
• [AWS Production Deployment](#aws-production-deployment)
• [Usage](#usage)
• [Streaming Responses](#streaming-responses)
• [How It Works](#how-it-works)
• [Technical Implementation](#technical-implementation)
• [Key Features](#key-features)
• [API Endpoints](#api-endpoints-1)
• [Event Types](#event-types)
• [Error Recovery](#error-recovery)
• [User Interface](#user-interface)
• [API Endpoints](#api-endpoints)
• [Authentication](#authentication)
• [Conversations](#conversations)
• [Chat](#chat)
• [Swagger API Documentation](#swagger-api-documentation)
• [Project Structure](#project-structure)
• [MCP Server (Model Context Protocol)](#mcp-server-model-context-protocol)
• [Agentic AI Pipeline](#agentic-ai-pipeline)
• [Dockerization](#dockerization)
• [OpenAPI Specification](#openapi-specification)
• [CI / CD with GitHub Actions](#ci--cd-with-github-actions)
• [Testing](#testing)
• [Contributing](#contributing)
• [License](#license)

Live App

> [!IMPORTANT] > Currently, the app is deployed live on Vercel at: https://lumina-david.vercel.app/. Feel free to check it out! > > For the backend (with Swagger docs), it is deployed live also on Vercel at: https://ai-assistant-chatbot-server.vercel.app/.

Alternatively, the backup app is deployed live on Netlify at: https://lumina-ai-chatbot.netlify.app/.

> [!TIP] > Go straight to https://lumina-david.vercel.app/chat if you want to chat with the AI right away!

Key Technologies

Features

• AI Chatbot: Ask questions about David Nguyen and general topics; receive responses from an AI.
• User Authentication: Sign up, log in, and log out using JWT authentication.
• Passkey (WebAuthn) Sign-in: Passwordless login with Touch ID, Face ID, Windows Hello, or a phone via QR. Supports discoverable (usernameless) credentials, an optional post-signup enrollment dialog, and per-user passkey management at /passkeys (list/add/nickname/revoke). Backed by @simplewebauthn/server v9 with a TTL-indexed challenges collection consumed exactly once. Email + password remains as a fallback.
• Toast Notifications: Global ToastProvider surfaces auth, passkey, and API errors in non-blocking snackbars instead of alert() dialogs.
• Conversation History: Save, retrieve, rename, and search past conversations (only for authenticated users).
• Fast Conversation Loading: The conversation list and search endpoints return metadata only (no messages) via field projection and .lean(), backed by a compound index, and the signed-in conversation list is cached client-side (stale-while-revalidate) so reloads render instantly.
• Auto-Generated Titles: AI automatically generates concise, descriptive titles for new conversations based on the first message.
• Grounded Knowledge Base: RAG (Retrieval-Augmented Generation) with Pinecone vector search and Neo4j graph traversal, plus inline citations; knowledge is managed via CLI (REPL or one-off commands) with manifest-based batch sync for easy knowledge management.
• Hybrid Graph + Vector RAG: Parallel retrieval from Pinecone (semantic similarity) and Neo4j (entity-relationship traversal) with intelligent result merging, dual-source scoring, exhaustive list retrieval (automatically fetches ALL chunks from a dominant source for "list all" queries), batched entity extraction (5 chunks per LLM call for efficiency), and model rotation across 6 Gemini models for resilience. Retrieval paths are isolated via Promise.allSettled, and a file-backed static resume fallback is used when live retrieval backends fail.
• Topic-Aware Full-Source Augmentation: When a query maps to a known topic (experience/career, education, certifications, publications, awards, etc.), the backend deterministically pulls the full canonical knowledge source for that topic so answers never omit items that fall below the top-K cutoff. Broadened query variants plus resilient embedding/graph retries further improve recall.
• Dynamic Responses: AI-generated responses with markdown formatting for rich text.
• Interactive Chat: Real-time chat interface with smooth animations and transitions.
• Reset Password: Verify email and reset a user's password.
• Streaming Responses: AI responses are streamed in real-time using Server-Sent Events (SSE) for a more natural conversation flow.
• Lightning-Fast Development: Built with Vite for instant HMR and optimized production builds.
• Responsive UI: Built with React and Material‑UI (MUI) with a fully responsive, modern, and animated interface.
• Animated 3D/WebGL Hero: A fully procedural Three.js / React Three Fiber scene (client/src/components/three/LuminaScene.tsx) with no binary assets — all geometry and GLSL shaders are generated in code. It renders a simplex-noise vertex-displaced icosahedron "core" with iridescent fresnel shading, an additive fresnel halo, a ~6k-point GPU particle starfield, and orbiting knowledge-node accents with glow rings. The scene is theme-aware (light/dark), mouse-parallax, scroll-reactive, and fully responsive (device-tiered particle counts and DPR for mobile/tablet/desktop). It respects prefers-reduced-motion, feature-detects WebGL with a graceful fallback, is pointer-events: none, and is lazy-loaded/code-split. Used as the landing background and reused as the ambient backdrop on the auth pages.
• Landing Page: A dynamic landing page with animations, feature cards, and call-to-action buttons.
• Branded Auth & Legal Pages: Login, signup, forgot-password, passkeys, and terms pages share a cohesive, theme-aware glassmorphism design system, including a signup password-strength meter with a live match indicator, an enhanced post-signup passkey enrollment dialog, and a 2-step password-reset flow.
• Guest Mode: Users may interact with the AI assistant as a guest, though conversations will not be saved.
• Message Editing with Conversation Branching: Edit any previously sent message to branch the conversation — the history is truncated at the edit point and a fresh AI response is generated from the revised message.
• Conversation Search: Search through conversation titles and messages to find relevant discussions.
• Collapsible Sidebar: A sidebar that displays conversation history, allowing users to switch between conversations easily.
• Reinforced Learning from Human Feedback (RLHF): Implement a feedback loop to continuously improve the AI's responses based on user interactions.
• Dark/Light Mode: Users can toggle between dark and light themes, with the preference stored in local storage.
• Enterprise-Grade Deployment: Deployed with blue/green & canary deployment strategies on AWS & Terraform for zero-downtime updates.
• Comprehensive Testing: Unit and integration tests for both frontend and backend using Jest and React Testing Library.
• CI/CD Pipeline: Automated testing and deployment using GitHub Actions.
• Standalone MCP Server: 30+ tools via Model Context Protocol for AI client integration.
• Agentic AI Pipeline: Multi-agent LangGraph pipeline with MCP-powered tool access.

Architecture

The project follows a modern, full-stack architecture with clear separation of concerns across three main layers:

• Frontend Layer:

A React application built with TypeScript and Material-UI (MUI) that provides:

• Modern, animated user interface with responsive design
• Client-side routing with React Router
• JWT-based authentication and authorization
• Real-time chat interface with markdown support
• Inline message editing with conversation branching
• Theme toggling (dark/light mode)
• Collapsible sidebar for conversation history
• WebSockets & SSE for streaming AI responses

• Backend Layer:

An Express.js server written in TypeScript that handles:

• RESTful API endpoints for authentication and data management
• JWT token generation and validation
• User authentication (signup, login, password reset)
• Conversation management (CRUD operations)
• Integration with AI services
• Request validation and error handling

• AI/ML Layer:

Hybrid RAG (Retrieval-Augmented Generation) implementation that includes:

• Retrieval: Hybrid search using Pinecone (vector similarity) and Neo4j (graph traversal) in parallel
• Vector Search: Semantic search with Pinecone for unstructured data
• Knowledge Graph: Entity extraction and relationship mapping stored in Neo4j AuraDB
• Result Merging: Intelligent merging of vector and graph results with dual-source scoring and exhaustive retrieval for list queries
• Entity Extraction: Batched extraction of entities from retrieved chunks for efficient graph traversal
• Augmentation: Context building with conversation history
• Generation: Response generation using Google Gemini AI
• Knowledge Storage: CLI-driven ingestion into Pinecone with citations returned in responses
• Graceful Degradation: System operates as vector-only if Neo4j is unavailable, and can fall back to static resume context from local knowledge files when live retrieval backends fail

For detailed architecture documentation, including component diagrams, data flows, and deployment strategies, see [ARCHITECTURE.md](ARCHITECTURE.md).

High-Level System Architecture

graph TB
    subgraph "Client Layer"
        Browser[Web Browser]
        React[React Application]
    end

    subgraph "API Gateway"
        LB[Load Balancer / CDN]
    end

    subgraph "Application Layer"
        API[Express.js API Server]
        Auth[Authentication Service]
        Chat[Chat Service]
        Conv[Conversation Service]
    end

    subgraph "AI/ML Layer"
        RAG[RAG Pipeline]
        Gemini[Google Gemini AI]
        Embed[Embedding Service]
    end

    subgraph "Data Layer"
        MongoDB[(MongoDB)]
        Pinecone[(Pinecone Vector DB)]
        Neo4j[(Neo4j Graph DB)]
    end

    Browser --> React
    React --> LB
    LB --> API

    API --> Auth
    API --> Chat
    API --> Conv

    Chat --> RAG
    RAG --> Embed
    RAG --> Gemini
    RAG --> Pinecone
    RAG --> Neo4j

    Auth --> MongoDB
    Conv --> MongoDB
    Chat --> MongoDB

    style React fill:#4285F4
    style API fill:#339933
    style MongoDB fill:#47A248
    style Pinecone fill:#FF6F61
    style Neo4j fill:#008CC1
    style Gemini fill:#4285F4

RAG (Retrieval-Augmented Generation) Flow

Hybrid retrieval from Pinecone and Neo4j in parallel, followed by intelligent merging, augmentation with conversation history, and response generation with Google Gemini AI. One failing retrieval path never blocks the other, and if live retrieval backends fail, Lumina can fall back to static resume context loaded from local manifest/files.

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant Pinecone
    participant Neo4j
    participant Gemini
    participant MongoDB

    User->>Frontend: Send chat message
    Frontend->>Backend: POST /api/chat/auth
    Backend->>MongoDB: Fetch conversation history
    MongoDB-->>Backend: Previous messages

    Note over Backend,Neo4j: Retrieval Phase (Parallel)
    par Parallel Retrieval
        Backend->>Pinecone: Vector similarity search
        Pinecone-->>Backend: Top-K vector matches
    and
        Backend->>Neo4j: Extract query entities + graph traversal
        Neo4j-->>Backend: Top-K graph matches
    end
    Backend->>Backend: Merge & deduplicate results

    Note over Backend,Gemini: Augmentation Phase
    Backend->>Backend: Build augmented context
    Backend->>Gemini: Send enriched prompt

    Note over Gemini: Generation Phase
    Gemini->>Gemini: Generate response
    Gemini-->>Backend: AI response + citations

    Backend->>MongoDB: Save message & sources
    MongoDB-->>Backend: Saved
    Backend-->>Frontend: Return AI response
    Frontend-->>User: Display response

Data Flow Architecture

flowchart LR
    subgraph "Frontend"
        UI[User Interface]
        State[State Management]
        API_Client[API Client]
    end

    subgraph "Backend API"
        Routes[Route Handlers]
        Middleware[Auth Middleware]
        Services[Business Logic]
    end

    subgraph "Data Sources"
        MongoDB[(MongoDB)]
        Pinecone[(Pinecone)]
        Neo4j[(Neo4j)]
        Gemini[Gemini API]
    end

    UI --> State
    State --> API_Client
    API_Client -.HTTP/REST.-> Routes
    Routes --> Middleware
    Middleware --> Services

    Services --> MongoDB
    Services --> Pinecone
    Services --> Neo4j
    Services --> Gemini

    MongoDB -.Data.-> Services
    Pinecone -.Vectors.-> Services
    Neo4j -.Graph.-> Services
    Gemini -.AI Response.-> Services

    Services -.JSON.-> Routes
    Routes -.Response.-> API_Client
    API_Client --> State
    State --> UI

    style UI fill:#4285F4
    style Services fill:#339933
    style MongoDB fill:#47A248
    style Pinecone fill:#FF6F61
    style Neo4j fill:#008CC1
    style Gemini fill:#4285F4

> [!NOTE] > These diagrams provide a high-level overview of the system architecture. For detailed component interactions, database schemas, deployment strategies, and security architecture, please refer to [ARCHITECTURE.md](ARCHITECTURE.md).

Detailed Architecture Documentation

For comprehensive architecture documentation including:

• Detailed component diagrams and interactions
• Database schema and data models
• Security architecture and authentication flows
• Deployment strategies (Docker, AWS, Terraform)
• Performance optimization and scalability
• Monitoring and observability
• Disaster recovery and backup strategies

Please see [ARCHITECTURE.md](ARCHITECTURE.md)

Setup & Installation

Backend Setup

1. Clone the repository:

``bash git clone https://github.com/hoangsonww/AI-Assistant-Chatbot.git cd AI-Assistant-Chatbot/server ``

1. Install dependencies:

``bash npm install ``

1. Environment Variables:

Create a .env file in the server folder with the following (adjust values as needed):

```env PORT=5000 MONGODBURI=mongodb://localhost:27017/ai-assistant JWTSECRET=yourjwtsecrethere GOOGLEAIAPIKEY=yourgoogleaiapikeyhere PINECONEAPIKEY=yourpineconeapikeyhere PINECONEINDEX_NAME=lumina-index

# Neo4j AuraDB (optional — enables graph RAG) NEO4JURI=neo4j+s://your-instance.databases.neo4j.io NEO4JUSERNAME=yourusername NEO4JPASSWORD=your_pa

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hoangsonww
• Source: hoangsonww/AI-RAG-Assistant-Chatbot
• License: MIT
• Homepage: https://lumina-david.vercel.app

Install and usage instructions live in the source repository linked above.