{"id":27995779,"url":"https://github.com/hoangsonww/ai-rag-assistant-chatbot","last_synced_at":"2026-03-15T07:37:42.139Z","repository":{"id":279316382,"uuid":"928634501","full_name":"hoangsonww/AI-RAG-Assistant-Chatbot","owner":"hoangsonww","description":"👨🏻‍💻 Meet Lumina – my personal chatbot assistant designed to answer any questions. Powered by Optuna, RAG, LangChain, and Pinecone vector database, Lumina offers friendly support and smart solutions tailored for all conversations. Created as part of the mid-term project for COMP-488 at UNC.","archived":false,"fork":false,"pushed_at":"2025-04-27T16:13:25.000Z","size":10370,"stargazers_count":27,"open_issues_count":0,"forks_count":20,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-27T17:25:44.390Z","etag":null,"topics":["api","artificial-intelligence","chat-application","chatbot","docker","express","fullstack-development","langchain","lumina","machine-learning","mongodb","nodejs","personal-assistant","python","rag","react","retreival-augmented-generation","typescript","vercel"],"latest_commit_sha":null,"homepage":"https://lumina-david.vercel.app/chat","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hoangsonww.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-07T00:43:42.000Z","updated_at":"2025-04-27T16:13:29.000Z","dependencies_parsed_at":"2025-03-25T06:21:38.556Z","dependency_job_id":"130f601f-4db7-4b16-8872-31b15db9e315","html_url":"https://github.com/hoangsonww/AI-RAG-Assistant-Chatbot","commit_stats":null,"previous_names":["hoangsonww/ai-assistant-chatbot","hoangsonww/ai-rag-assistant-chatbot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FAI-RAG-Assistant-Chatbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FAI-RAG-Assistant-Chatbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FAI-RAG-Assistant-Chatbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FAI-RAG-Assistant-Chatbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hoangsonww","download_url":"https://codeload.github.com/hoangsonww/AI-RAG-Assistant-Chatbot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253149380,"owners_count":21861717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","artificial-intelligence","chat-application","chatbot","docker","express","fullstack-development","langchain","lumina","machine-learning","mongodb","nodejs","personal-assistant","python","rag","react","retreival-augmented-generation","typescript","vercel"],"created_at":"2025-05-08T20:53:46.706Z","updated_at":"2026-03-15T07:37:42.128Z","avatar_url":"https://github.com/hoangsonww.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# My Personal AI Assistant Project - Lumina 👨🏻‍💻\n\n**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 \u0026 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. 🚀\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://lumina-david.vercel.app/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n    \u003cimg src=\"img/logo.jpeg\" alt=\"Lumina Logo\" width=\"45%\" style=\"border-radius: 10px\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Table of Contents\n\n- [Live App](#live-app)\n  - [Key Technologies](#key-technologies)\n- [Features](#features)\n- [Architecture](#architecture)\n  - [High-Level System Architecture](#high-level-system-architecture)\n  - [RAG Flow](#rag-retrieval-augmented-generation-flow)\n  - [Data Flow Architecture](#data-flow-architecture)\n- [Detailed Architecture Documentation](#detailed-architecture-documentation)\n- [Setup \u0026 Installation](#setup--installation)\n  - [Backend Setup](#backend-setup)\n  - [Frontend Setup](#frontend-setup)\n  - [AI/ML Setup](#aiml-setup)\n- [Deployment](#deployment)\n  - [Current Deployment (Vercel)](#current-deployment-vercel)\n  - [Docker Deployment](#docker-deployment)\n  - [AWS Production Deployment](#aws-production-deployment)\n- [Usage](#usage)\n- [Streaming Responses](#streaming-responses)\n  - [How It Works](#how-it-works)\n  - [Technical Implementation](#technical-implementation)\n  - [Key Features](#key-features)\n  - [API Endpoints](#api-endpoints-1)\n  - [Event Types](#event-types)\n  - [Error Recovery](#error-recovery)\n- [User Interface](#user-interface)\n- [API Endpoints](#api-endpoints)\n  - [Authentication](#authentication)\n  - [Conversations](#conversations)\n  - [Chat](#chat)\n  - [Swagger API Documentation](#swagger-api-documentation)\n- [Project Structure](#project-structure)\n- [Agentic AI Pipeline](#agentic-ai-pipeline)\n- [Dockerization](#dockerization)\n- [OpenAPI Specification](#openapi-specification)\n- [CI / CD with GitHub Actions](#ci--cd-with-github-actions)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Live App\n\n\u003e [!IMPORTANT]\n\u003e Currently, the app is deployed live on Vercel at: [https://lumina-david.vercel.app/](https://lumina-david.vercel.app). Feel free to check it out!\n\u003e \n\u003e For the backend (with Swagger docs), it is deployed live also on Vercel at: [https://ai-assistant-chatbot-server.vercel.app/](https://ai-assistant-chatbot-server.vercel.app/).\n\nAlternatively, the backup app is deployed live on Netlify at: [https://lumina-ai-chatbot.netlify.app/](https://lumina-ai-chatbot.netlify.app/).\n\n\u003e [!TIP]\n\u003e Go straight to [https://lumina-david.vercel.app/chat](https://lumina-david.vercel.app/chat) if you want to chat with the AI right away!\n\n### Key Technologies\n\n![Vite](https://img.shields.io/badge/vite-%23646CFF.svg?style=for-the-badge\u0026logo=vite\u0026logoColor=white)\n![Node.js](https://img.shields.io/badge/Node.js-339933?style=for-the-badge\u0026logo=nodedotjs\u0026logoColor=white)\n![Express](https://img.shields.io/badge/Express.js-000000?style=for-the-badge\u0026logo=express\u0026logoColor=white)\n![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)\n![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge\u0026logo=javascript\u0026logoColor=black)\n![React](https://img.shields.io/badge/React-61DAFB?style=for-the-badge\u0026logo=react\u0026logoColor=black)\n![MongoDB](https://img.shields.io/badge/MongoDB-47A248?style=for-the-badge\u0026logo=mongodb\u0026logoColor=white)\n![Pinecone](https://img.shields.io/badge/Pinecone-FF6F61?style=for-the-badge\u0026logo=googledataflow\u0026logoColor=white)\n![JWT](https://img.shields.io/badge/JWT-black?style=for-the-badge\u0026logo=json-web-tokens)\n![Material UI](https://img.shields.io/badge/Material_UI-007FFF?style=for-the-badge\u0026logo=mui\u0026logoColor=white)\n![Vercel](https://img.shields.io/badge/Vercel-000000?style=for-the-badge\u0026logo=vercel\u0026logoColor=white)\n![Netlify](https://img.shields.io/badge/Netlify-00C7B7?style=for-the-badge\u0026logo=netlify\u0026logoColor=white)\n![Swagger](https://img.shields.io/badge/Swagger-85EA2D?style=for-the-badge\u0026logo=swagger\u0026logoColor=white)\n![RAG](https://img.shields.io/badge/Retrieval_Augmented_Generation-FFCA28?style=for-the-badge\u0026logo=chatbot\u0026logoColor=black)\n![WebSockets](https://img.shields.io/badge/WebSockets-008000?style=for-the-badge\u0026logo=socketdotio\u0026logoColor=white)\n![Server-Sent Events](https://img.shields.io/badge/Server_Sent_Events-800080?style=for-the-badge\u0026logo=serverless\u0026logoColor=white)\n![OpenAI](https://img.shields.io/badge/OpenAI-412991?style=for-the-badge\u0026logo=c\u0026logoColor=white)\n![Google AI](https://img.shields.io/badge/GoogleAI-4285F4?style=for-the-badge\u0026logo=google\u0026logoColor=white)\n![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)\n![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white)\n![Jupyter Notebook](https://img.shields.io/badge/Jupyter_Notebook-FFCA28?style=for-the-badge\u0026logo=jupyter\u0026logoColor=black)\n![AWS](https://img.shields.io/badge/AWS-232F3E?style=for-the-badge\u0026logo=task\u0026logoColor=white)\n![Terraform](https://img.shields.io/badge/Terraform-7B42BC?style=for-the-badge\u0026logo=terraform\u0026logoColor=white)\n![Docker Compose](https://img.shields.io/badge/Docker_Compose-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white)\n![Nodemon](https://img.shields.io/badge/Nodemon-76D04B?style=for-the-badge\u0026logo=nodemon\u0026logoColor=white)\n![ESLint](https://img.shields.io/badge/ESLint-4B32C3?style=for-the-badge\u0026logo=eslint\u0026logoColor=white)\n![Git](https://img.shields.io/badge/Git-F05032?style=for-the-badge\u0026logo=git\u0026logoColor=white)\n![GitHub](https://img.shields.io/badge/GitHub-181717?style=for-the-badge\u0026logo=github\u0026logoColor=white)\n![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-2088FF?style=for-the-badge\u0026logo=github-actions\u0026logoColor=white)\n![Jest](https://img.shields.io/badge/Jest-C21325?style=for-the-badge\u0026logo=jest\u0026logoColor=white)\n\n## Features\n\n- **AI Chatbot:** Ask questions about David Nguyen and general topics; receive responses from an AI.\n- **User Authentication:** Sign up, log in, and log out using JWT authentication.\n- **Conversation History:** Save, retrieve, rename, and search past conversations (only for authenticated users).\n- **Auto-Generated Titles:** AI automatically generates concise, descriptive titles for new conversations based on the first message.\n- **Grounded Knowledge Base:** RAG (Retrieval-Augmented Generation) with Pinecone and inline citations; knowledge is managed via CLI (REPL or one-off commands).\n- **Dynamic Responses:** AI-generated responses with `markdown` formatting for rich text.\n- **Interactive Chat:** Real-time chat interface with smooth animations and transitions.\n- **Reset Password:** Verify email and reset a user's password.\n- **Streaming Responses:** AI responses are streamed in real-time using Server-Sent Events (SSE) for a more natural conversation flow.\n- **Lightning-Fast Development:** Built with Vite for instant HMR and optimized production builds.\n- **Responsive UI:** Built with React and Material‑UI (MUI) with a fully responsive, modern, and animated interface.\n- **Landing Page:** A dynamic landing page with animations, feature cards, and call-to-action buttons.\n- **Guest Mode:** Users may interact with the AI assistant as a guest, though conversations will not be saved.\n- **Conversation Search:** Search through conversation titles and messages to find relevant discussions.\n- **Collapsible Sidebar:** A sidebar that displays conversation history, allowing users to switch between conversations easily.\n- **Reinforced Learning from Human Feedback (RLHF):** Implement a feedback loop to continuously improve the AI's responses based on user interactions.\n- **Dark/Light Mode:** Users can toggle between dark and light themes, with the preference stored in local storage.\n- **Enterprise-Grade Deployment:** Deployed with blue/green \u0026 canary deployment strategies on AWS \u0026 Terraform for zero-downtime updates.\n- **Comprehensive Testing:** Unit and integration tests for both frontend and backend using Jest and React Testing Library.\n- **CI/CD Pipeline:** Automated testing and deployment using GitHub Actions.\n\n## Architecture\n\nThe project follows a modern, full-stack architecture with clear separation of concerns across three main layers:\n\n- **Frontend Layer:**\n  A React application built with TypeScript and Material-UI (MUI) that provides:\n  - Modern, animated user interface with responsive design\n  - Client-side routing with React Router\n  - JWT-based authentication and authorization\n  - Real-time chat interface with markdown support\n  - Theme toggling (dark/light mode)\n  - Collapsible sidebar for conversation history\n  - WebSockets \u0026 SSE for streaming AI responses\n\n- **Backend Layer:**\n  An Express.js server written in TypeScript that handles:\n  - RESTful API endpoints for authentication and data management\n  - JWT token generation and validation\n  - User authentication (signup, login, password reset)\n  - Conversation management (CRUD operations)\n  - Integration with AI services\n  - Request validation and error handling\n\n- **AI/ML Layer:**\n  RAG (Retrieval-Augmented Generation) implementation that includes:\n  - **Retrieval**: Vector similarity search using Pinecone\n  - **Augmentation**: Context building with conversation history\n  - **Generation**: Response generation using Google Gemini AI\n  - **Knowledge Storage**: CLI-driven ingestion into Pinecone with citations returned in responses\n\nFor detailed architecture documentation, including component diagrams, data flows, and deployment strategies, see [ARCHITECTURE.md](ARCHITECTURE.md).\n\n### High-Level System Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Client Layer\"\n        Browser[Web Browser]\n        React[React Application]\n    end\n\n    subgraph \"API Gateway\"\n        LB[Load Balancer / CDN]\n    end\n\n    subgraph \"Application Layer\"\n        API[Express.js API Server]\n        Auth[Authentication Service]\n        Chat[Chat Service]\n        Conv[Conversation Service]\n    end\n\n    subgraph \"AI/ML Layer\"\n        RAG[RAG Pipeline]\n        Gemini[Google Gemini AI]\n        Embed[Embedding Service]\n    end\n\n    subgraph \"Data Layer\"\n        MongoDB[(MongoDB)]\n        Pinecone[(Pinecone Vector DB)]\n    end\n\n    Browser --\u003e React\n    React --\u003e LB\n    LB --\u003e API\n\n    API --\u003e Auth\n    API --\u003e Chat\n    API --\u003e Conv\n\n    Chat --\u003e RAG\n    RAG --\u003e Embed\n    RAG --\u003e Gemini\n    RAG --\u003e Pinecone\n\n    Auth --\u003e MongoDB\n    Conv --\u003e MongoDB\n    Chat --\u003e MongoDB\n\n    style React fill:#4285F4\n    style API fill:#339933\n    style MongoDB fill:#47A248\n    style Pinecone fill:#FF6F61\n    style Gemini fill:#4285F4\n```\n\n### RAG (Retrieval-Augmented Generation) Flow\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Frontend\n    participant Backend\n    participant Pinecone\n    participant Gemini\n    participant MongoDB\n\n    User-\u003e\u003eFrontend: Send chat message\n    Frontend-\u003e\u003eBackend: POST /api/chat/auth\n    Backend-\u003e\u003eMongoDB: Fetch conversation history\n    MongoDB--\u003e\u003eBackend: Previous messages\n\n    Note over Backend,Pinecone: Retrieval Phase\n    Backend-\u003e\u003ePinecone: Generate embedding \u0026 search\n    Pinecone--\u003e\u003eBackend: Top-K relevant documents\n\n    Note over Backend,Gemini: Augmentation Phase\n    Backend-\u003e\u003eBackend: Build augmented context\n    Backend-\u003e\u003eGemini: Send enriched prompt\n\n    Note over Gemini: Generation Phase\n    Gemini-\u003e\u003eGemini: Generate response\n    Gemini--\u003e\u003eBackend: AI response + citations\n\n    Backend-\u003e\u003eMongoDB: Save message \u0026 sources\n    MongoDB--\u003e\u003eBackend: Saved\n    Backend--\u003e\u003eFrontend: Return AI response\n    Frontend--\u003e\u003eUser: Display response\n```\n\n### Data Flow Architecture\n\n```mermaid\nflowchart LR\n    subgraph \"Frontend\"\n        UI[User Interface]\n        State[State Management]\n        API_Client[API Client]\n    end\n\n    subgraph \"Backend API\"\n        Routes[Route Handlers]\n        Middleware[Auth Middleware]\n        Services[Business Logic]\n    end\n\n    subgraph \"Data Sources\"\n        MongoDB[(MongoDB)]\n        Pinecone[(Pinecone)]\n        Gemini[Gemini API]\n    end\n\n    UI --\u003e State\n    State --\u003e API_Client\n    API_Client -.HTTP/REST.-\u003e Routes\n    Routes --\u003e Middleware\n    Middleware --\u003e Services\n\n    Services --\u003e MongoDB\n    Services --\u003e Pinecone\n    Services --\u003e Gemini\n\n    MongoDB -.Data.-\u003e Services\n    Pinecone -.Vectors.-\u003e Services\n    Gemini -.AI Response.-\u003e Services\n\n    Services -.JSON.-\u003e Routes\n    Routes -.Response.-\u003e API_Client\n    API_Client --\u003e State\n    State --\u003e UI\n\n    style UI fill:#4285F4\n    style Services fill:#339933\n    style MongoDB fill:#47A248\n    style Pinecone fill:#FF6F61\n    style Gemini fill:#4285F4\n```\n\n\u003e [!NOTE]\n\u003e 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).\n\n## Detailed Architecture Documentation\n\nFor comprehensive architecture documentation including:\n- Detailed component diagrams and interactions\n- Database schema and data models\n- Security architecture and authentication flows\n- Deployment strategies (Docker, AWS, Terraform)\n- Performance optimization and scalability\n- Monitoring and observability\n- Disaster recovery and backup strategies\n\nPlease see **[ARCHITECTURE.md](ARCHITECTURE.md)**\n\n## Setup \u0026 Installation\n\n### Backend Setup\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/hoangsonww/AI-Assistant-Chatbot.git\n   cd AI-Assistant-Chatbot/server\n   ```\n\n2. **Install dependencies:**\n\n   ```bash\n   npm install\n   ```\n\n3. **Environment Variables:**  \n   Create a `.env` file in the `server` folder with the following (adjust values as needed):\n\n   ```env\n   PORT=5000\n   MONGODB_URI=mongodb://localhost:27017/ai-assistant\n   JWT_SECRET=your_jwt_secret_here\n   GOOGLE_AI_API_KEY=your_google_ai_api_key_here\n   PINECONE_API_KEY=your_pinecone_api_key_here\n   PINECONE_INDEX_NAME=lumina-index\n   ```\n\n4. **Run the server in development mode:**\n\n   ```bash\n   npm run dev\n   ```\n\n   This uses nodemon with `ts-node` to watch for file changes.\n\n### Frontend Setup\n\n1. **Navigate to the client folder:**\n\n   ```bash\n   cd ../client\n   ```\n\n2. **Install dependencies:**\n\n   ```bash\n   npm install\n   ```\n\n3. **Run the frontend development server:**\n\n   ```bash\n   npm start\n   ```\n\n   The app will run on [http://localhost:3000](http://localhost:3000) (or any other port you've specified in the `.env` file's `PORT` key).\n\n### AI/ML Setup\n\n1. Install necessary Node.js packages:\n\n   ```bash\n   npm install\n   ```\n\n2. Ingest knowledge into Pinecone with the CLI (run from `server/`):\n\n   ```bash\n   npm run knowledge:repl\n   ```\n\n   Or run a single upsert command (use `--external-id` to update later):\n\n   ```bash\n   npm run knowledge:upsert -- \\\n     --title \"Resume 2025\" \\\n     --file ./knowledge/resume.txt \\\n     --type resume \\\n     --tags \"resume,profile\" \\\n     --external-id \"resume-2025\"\n   ```\n\n3. Use the REPL to edit or delete sources (`edit \u003cid\u003e`, `delete \u003cid\u003e`) as your profile changes.\n4. Ensure you ingest at least one knowledge source before using the chatbot so responses can be grounded and cited.\n\n## Deployment\n\n### Current Deployment (Vercel)\n\nThe application is currently deployed on Vercel with the following setup:\n\n- **Frontend**: Deployed at [https://lumina-david.vercel.app/](https://lumina-david.vercel.app)\n- **Backend**: Deployed at [https://ai-assistant-chatbot-server.vercel.app/](https://ai-assistant-chatbot-server.vercel.app/)\n- **Database**: MongoDB Atlas (cloud-hosted)\n- **Vector Database**: Pinecone (cloud-hosted)\n\n#### Deployment Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Client Devices\"\n        Browser[Web Browser]\n        Mobile[Mobile Browser]\n    end\n    \n    subgraph \"CDN Layer\"\n        Vercel[Vercel Edge Network]\n        Netlify[Netlify CDN - Backup]\n    end\n    \n    subgraph \"Frontend Deployment\"\n        FrontendVercel[React App on Vercel]\n        FrontendNetlify[React App on Netlify]\n        StaticAssets[Static Assets]\n    end\n    \n    subgraph \"Backend Deployment\"\n        BackendVercel[Express API on Vercel]\n        ServerlessFunctions[Serverless Functions]\n    end\n    \n    subgraph \"External Services\"\n        MongoDB[(MongoDB Atlas)]\n        Pinecone[(Pinecone Vector DB)]\n        GeminiAPI[Google Gemini AI API]\n    end\n    \n    subgraph \"CI/CD Pipeline\"\n        GitHub[GitHub Repository]\n        GitHubActions[GitHub Actions]\n        AutoDeploy[Auto Deploy on Push]\n    end\n    \n    subgraph \"Monitoring \u0026 Analytics\"\n        VercelAnalytics[Vercel Analytics]\n        Logs[Application Logs]\n    end\n    \n    Browser --\u003e Vercel\n    Mobile --\u003e Vercel\n    Vercel --\u003e FrontendVercel\n    Netlify --\u003e FrontendNetlify\n    \n    FrontendVercel --\u003e StaticAssets\n    FrontendVercel --\u003e BackendVercel\n    FrontendNetlify --\u003e BackendVercel\n    \n    BackendVercel --\u003e ServerlessFunctions\n    ServerlessFunctions --\u003e MongoDB\n    ServerlessFunctions --\u003e Pinecone\n    ServerlessFunctions --\u003e GeminiAPI\n    \n    GitHub --\u003e GitHubActions\n    GitHubActions --\u003e AutoDeploy\n    AutoDeploy --\u003e Vercel\n    AutoDeploy --\u003e Netlify\n    \n    BackendVercel --\u003e VercelAnalytics\n    BackendVercel --\u003e Logs\n    FrontendVercel --\u003e VercelAnalytics\n    \n    style Browser fill:#4285F4\n    style Vercel fill:#000000\n    style FrontendVercel fill:#61DAFB\n    style BackendVercel fill:#339933\n    style MongoDB fill:#47A248\n    style Pinecone fill:#FF6F61\n    style GeminiAPI fill:#4285F4\n    style GitHub fill:#181717\n```\n\n### Docker Deployment\n\nRun the entire application stack locally using Docker:\n\n```bash\n# Build and start all services\ndocker-compose up --build\n\n# Or run in detached mode\ndocker-compose up -d\n\n# Stop all services\ndocker-compose down\n```\n\nThis will start:\n- Frontend on `http://localhost:3000`\n- Backend on `http://localhost:5000`\n- MongoDB on `localhost:27017`\n\n### AWS Production Deployment\n\nFor production-grade AWS deployment with high availability and scalability:\n\n```bash\n# Navigate to infrastructure directory\ncd terraform/\n\n# Initialize Terraform\nterraform init\n\n# Review deployment plan\nterraform plan\n\n# Deploy infrastructure\nterraform apply\n\n# Or use provided scripts\ncd ../aws/scripts/\n./deploy-production.sh\n```\n\n**AWS Infrastructure includes:**\n- ECS/Fargate for container orchestration\n- Application Load Balancer for traffic distribution\n- DocumentDB (MongoDB-compatible) for database\n- ElastiCache (Redis) for caching\n- CloudFront CDN for static asset delivery\n- CloudWatch for monitoring and logging\n- Auto-scaling groups for high availability\n- Multi-AZ deployment for fault tolerance\n\nSee [aws/README.md](aws/README.md) and [terraform/README.md](terraform/README.md) for detailed deployment instructions.\n\n## Usage\n\n- **Landing Page:**  \n  The landing page provides an overview of the app’s features and two main actions: Create Account (for new users) and Continue as Guest.\n\n- **Authentication:**  \n  Users can sign up, log in, and reset their password. Authenticated users can save and manage their conversation history.\n\n- **Chatting:**  \n  The main chat area allows users to interact with the AI assistant. The sidebar displays saved conversations (for logged-in users) and allows renaming and searching.\n\n- **Theme:**  \n  Toggle between dark and light mode via the navbar. The chosen theme is saved in local storage and persists across sessions.\n\n## Streaming Responses\n\nLumina features real-time streaming responses that make conversations feel more natural and engaging. Instead of waiting for the complete response, you'll see the AI's thoughts appear word-by-word as they're generated.\n\n### How It Works\n\nThe streaming implementation uses **Server-Sent Events (SSE)** and **WebSockets (optional)** to deliver AI responses in real-time:\n\n1. **User sends a message** → Frontend displays \"Processing Message...\"\n2. **Backend processes** → Shows \"Thinking \u0026 Reasoning...\"\n3. **Connection established** → Displays \"Connecting...\"\n4. **Streaming begins** → Text appears word-by-word with a blinking cursor\n5. **Response complete** → Message is saved to conversation history\n\n### Technical Implementation\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Frontend\n    participant Backend\n    participant Gemini AI\n    \n    User-\u003e\u003eFrontend: Send message\n    Frontend-\u003e\u003eFrontend: Show \"Processing...\"\n    Frontend-\u003e\u003eBackend: POST /api/chat/auth/stream\n    Backend-\u003e\u003eGemini AI: Request streaming response\n    \n    loop For each chunk\n        Gemini AI--\u003e\u003eBackend: Stream text chunk\n        Backend--\u003e\u003eFrontend: SSE: chunk data\n        Frontend-\u003e\u003eFrontend: Append to message bubble\n        Frontend-\u003e\u003eUser: Display growing text + cursor\n    end\n    \n    Gemini AI--\u003e\u003eBackend: Stream complete\n    Backend-\u003e\u003eBackend: Save to database\n    Backend--\u003e\u003eFrontend: SSE: done event\n    Frontend-\u003e\u003eFrontend: Finalize message\n```\n\n### Key Features\n\n- **Live Text Rendering:** See responses appear in real-time with markdown formatting\n- **Visual Feedback:** Multiple loading states (Processing → Thinking → Connecting → Streaming)\n- **Blinking Cursor:** Animated cursor indicates active streaming\n- **Automatic Retries:** Up to 3 retry attempts with exponential backoff (1s, 2s, 4s)\n- **Error Handling:** Graceful degradation with user-friendly error messages\n- **Works Everywhere:** Available for both authenticated and guest users\n\n### API Endpoints\n\n**Authenticated Streaming:**\n```\nPOST /api/chat/auth/stream\nContent-Type: application/json\nAuthorization: Bearer \u003ctoken\u003e\n\n{\n  \"message\": \"Your question here\",\n  \"conversationId\": \"optional-conversation-id\"\n}\n```\n\n**Guest Streaming:**\n```\nPOST /api/chat/guest/stream\nContent-Type: application/json\n\n{\n  \"message\": \"Your question here\",\n  \"guestId\": \"optional-guest-id\"\n}\n```\n\n### Event Types\n\nThe SSE stream sends different event types:\n\n- **`conversationId`/`guestId`:** Sent at the start with the conversation identifier\n- **`chunk`:** Each piece of text as it's generated from the AI\n- **`done`:** Signals that streaming is complete\n- **`error`:** Indicates an error occurred during streaming\n\n### Error Recovery\n\nIf a connection fails during streaming:\n1. **First retry:** Wait 1 second, then retry\n2. **Second retry:** Wait 2 seconds, then retry\n3. **Third retry:** Wait 4 seconds, then retry\n4. **All failed:** Display error message to user\n\nThe retry logic uses exponential backoff to avoid overwhelming the server while providing a smooth user experience.\n\n## User Interface\n\n### Landing Page\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/landing.png\" alt=\"Landing Page\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Homepage\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/home.png\" alt=\"Homepage\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Homepage - Empty State\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/empty-home.png\" alt=\"Homepage - Empty State\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Login Page\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/login.png\" alt=\"Login Page\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n#### Login Page - Dark Mode\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/login-dark.png\" alt=\"Login Page - Dark Mode\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Signup Page\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/register.png\" alt=\"Signup Page\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n#### Signup Page - Dark Mode\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/register-dark.png\" alt=\"Signup Page - Dark Mode\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Reset Password Page\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/reset-password.png\" alt=\"Reset Password Page\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n#### Reset Password Page - Dark Mode\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/reset-password-dark.png\" alt=\"Reset Password Page - Dark Mode\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Homepage - Unauthenticated User\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/unauthed-home.png\" alt=\"Homepage - Unauthenticated User\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n#### Homepage - Unauthenticated User - Dark Mode\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/unauthed-home-dark.png\" alt=\"Homepage - Unauthenticated User - Dark Mode\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### 404 Page\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/404.png\" alt=\"404 Page\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n## API Endpoints\n\n### Authentication\n\n- **POST /api/auth/signup:** Create a new user.\n- **POST /api/auth/login:** Authenticate a user and return a JWT.\n- **GET /api/auth/verify-email?email=example@example.com:** Check if an email exists.\n- **POST /api/auth/reset-password:** Reset a user's password.\n- **GET /api/auth/validate-token:** Validate the current JWT token.\n\n#### Authentication Flow\n\n```mermaid\nflowchart TB\n    Start([User Visits App]) --\u003e CheckAuth{Has Valid\u003cbr/\u003eToken?}\n    \n    CheckAuth --\u003e|Yes| Dashboard[Access Dashboard]\n    CheckAuth --\u003e|No| Landing[Landing Page]\n    \n    Landing --\u003e Choice{User Choice}\n    Choice --\u003e|Sign Up| SignupForm[Signup Form]\n    Choice --\u003e|Login| LoginForm[Login Form]\n    Choice --\u003e|Guest| GuestChat[Guest Chat Mode]\n    \n    SignupForm --\u003e ValidateSignup{Valid\u003cbr/\u003eCredentials?}\n    ValidateSignup --\u003e|No| SignupError[Show Error]\n    SignupError --\u003e SignupForm\n    ValidateSignup --\u003e|Yes| CreateUser[Create User in MongoDB]\n    CreateUser --\u003e GenerateToken[Generate JWT Token]\n    \n    LoginForm --\u003e ValidateLogin{Valid\u003cbr/\u003eCredentials?}\n    ValidateLogin --\u003e|No| LoginError[Show Error]\n    LoginError --\u003e LoginForm\n    ValidateLogin --\u003e|Yes| VerifyPassword[Verify Password with bcrypt]\n    VerifyPassword --\u003e|Invalid| LoginError\n    VerifyPassword --\u003e|Valid| GenerateToken\n    \n    GenerateToken --\u003e StoreToken[Store Token in LocalStorage]\n    StoreToken --\u003e Dashboard\n    \n    Dashboard --\u003e Protected[Protected Routes]\n    Protected --\u003e ConvHistory[Conversation History]\n    Protected --\u003e SavedChats[Saved Chats]\n    Protected --\u003e Settings[User Settings]\n    \n    GuestChat --\u003e TempStorage[Temporary Storage]\n    TempStorage --\u003e LimitedFeatures[Limited Features]\n    \n    Dashboard --\u003e Logout{Logout?}\n    Logout --\u003e|Yes| ClearToken[Clear Token]\n    ClearToken --\u003e Landing\n    \n    style Start fill:#4285F4\n    style Dashboard fill:#34A853\n    style GuestChat fill:#FBBC04\n    style GenerateToken fill:#EA4335\n    style CreateUser fill:#34A853\n```\n\n### Conversations\n\n- **POST /api/conversations:** Create a new conversation.\n- **GET /api/conversations:** Get all conversations for a user.\n- **GET /api/conversations/:id:** Retrieve a conversation by ID.\n- **PUT /api/conversations/:id:** Rename a conversation.\n- **GET /api/conversations/search/:query:** Search for conversations by title or message content.\n- **DELETE /api/conversations/:id:** Delete a conversation.\n\n#### Conversation Management Flow\n\n```mermaid\nflowchart LR\n    subgraph User[\"👤 User Actions\"]\n        NewChat[Start New Chat]\n        LoadChat[Load Existing Chat]\n        SearchChat[Search Conversations]\n        RenameChat[Rename Conversation]\n        DeleteChat[Delete Conversation]\n    end\n    \n    subgraph Frontend[\"⚛️ React Frontend\"]\n        ChatUI[Chat Interface]\n        Sidebar[Conversation Sidebar]\n        SearchBar[Search Bar]\n    end\n    \n    subgraph API[\"🔌 Express API\"]\n        ConvRoutes[api/conversations Route]\n        AuthMiddleware{JWT Auth}\n    end\n    \n    subgraph Database[\"🗄️ MongoDB\"]\n        ConvCollection[(Conversations Collection)]\n        UserCollection[(Users Collection)]\n    end\n    \n    subgraph Operations[\"📊 CRUD Operations\"]\n        Create[Create]\n        Read[Read]\n        Update[Update]\n        Delete[Delete]\n    end\n    \n    NewChat --\u003e ChatUI\n    LoadChat --\u003e Sidebar\n    SearchChat --\u003e SearchBar\n    RenameChat --\u003e Sidebar\n    DeleteChat --\u003e Sidebar\n    \n    ChatUI --\u003e ConvRoutes\n    Sidebar --\u003e ConvRoutes\n    SearchBar --\u003e ConvRoutes\n    \n    ConvRoutes --\u003e AuthMiddleware\n    AuthMiddleware --\u003e|Valid Token| Operations\n    AuthMiddleware --\u003e|Invalid Token| ErrorAuth[401 Unauthorized]\n    \n    Create --\u003e ConvCollection\n    Read --\u003e ConvCollection\n    Update --\u003e ConvCollection\n    Delete --\u003e ConvCollection\n    \n    ConvCollection -.User Reference.-\u003e UserCollection\n    \n    ConvCollection --\u003e ConvRoutes\n    ConvRoutes --\u003e Frontend\n    \n    style ChatUI fill:#4285F4\n    style ConvCollection fill:#47A248\n    style AuthMiddleware fill:#EA4335\n    style Operations fill:#34A853\n```\n\n### Chat\n\n- **POST /api/chat/auth:** Process a chat query for authenticated users and return an AI-generated response.\n- **POST /api/chat/auth/stream:** Stream AI responses in real-time for authenticated users using Server-Sent Events (SSE).\n- **POST /api/chat/guest:** Process a chat query for guest users and return an AI-generated response.\n- **POST /api/chat/guest/stream:** Stream AI responses in real-time for guest users using Server-Sent Events (SSE).\n\n### Swagger API Documentation\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/swagger.png\" alt=\"Swagger API Documentation\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n## Project Structure\n\n```\nAI-Assistant-Chatbot/\n├── docker-compose.yml\n├── openapi.yaml\n├── README.md\n├── ARCHITECTURE.md\n├── LICENSE\n├── Jenkinsfile\n├── package.json\n├── tsconfig.json\n├── .env\n├── shell/                          # Shell scripts for app setups\n├── terraform/                      # Infrastructure as Code (Terraform)\n├── aws/                            # AWS deployment configurations\n├── img/                            # Images and screenshots\n├── agentic_ai/                     # Agentic AI pipeline in Python\n├── client/                         # Frontend React application\n│   ├── package.json\n│   ├── tsconfig.json\n│   ├── docker-compose.yml\n│   ├── Dockerfile\n│   └── src/\n│       ├── App.tsx\n│       ├── index.tsx\n│       ├── theme.ts\n│       ├── globals.css\n│       ├── index.css\n│       ├── dev/\n│       │   ├── palette.tsx\n│       │   ├── previews.tsx\n│       │   ├── index.ts\n│       │   └── useInitial.ts\n│       ├── services/\n│       │   └── api.ts              # API client with streaming support\n│       ├── types/\n│       │   ├── conversation.d.ts\n│       │   └── user.d.ts\n│       ├── components/\n│       │   ├── Navbar.tsx\n│       │   ├── Sidebar.tsx\n│       │   ├── ChatArea.tsx        # Main chat interface with streaming\n│       │   └── CopyIcon.tsx\n│       ├── styles/\n│       │   └── (various style files)\n│       └── pages/\n│           ├── LandingPage.tsx\n│           ├── Home.tsx\n│           ├── Login.tsx\n│           ├── Signup.tsx\n│           ├── NotFoundPage.tsx\n│           ├── ForgotPassword.tsx\n│           └── Terms.tsx\n└── server/                         # Backend Express application\n    ├── package.json\n    ├── tsconfig.json\n    ├── Dockerfile\n    ├── docker-compose.yml\n    └── src/\n        ├── server.ts\n        ├── models/\n        │   ├── Conversation.ts\n        │   ├── GuestConversation.ts\n        │   ├── KnowledgeSource.ts\n        │   └── User.ts\n        ├── routes/\n        │   ├── auth.ts\n        │   ├── conversations.ts\n        │   ├── chat.ts             # Authenticated chat with streaming\n        │   └── guest.ts            # Guest chat with streaming\n        ├── services/\n        │   ├── geminiService.ts    # AI service with streaming support\n        │   ├── knowledgeBase.ts    # Chunking, embeddings, retrieval\n        │   └── pineconeClient.ts\n        ├── scripts/\n        │   └── knowledgeCli.ts     # CLI + REPL ingestion\n        ├── utils/\n        │   └── (utility functions)\n        ├── middleware/\n        │   └── auth.ts\n        └── public/\n            └── favicon.ico\n```\n\n## Agentic AI Pipeline\n\nThere is also a separate Agentic AI pipeline implemented in Python. This pipeline demonstrates how to create an autonomous agent that can perform tasks using tools and interact with the AI model.\n\nThe pipeline is located in the `agentic_ai/` directory and is optional for the main assistant.\n\n\u003e [!TIP]\n\u003e For more information on the Agentic AI pipeline, please refer to the [`agentic_ai/README.md`](agentic_ai/README.md) file.\n\n## Dockerization\n\nTo run the application using Docker, simply run `docker-compose up` in the root directory of the project. This will start both the backend and frontend services as defined in the `docker-compose.yml` file.\n\n**Why Dockerize?**\n\n- **Consistency:** Ensures the application runs the same way in different environments.\n- **Isolation:** Keeps dependencies and configurations contained.\n- **Scalability:** Makes it easier to scale services independently.\n- **Simplified Deployment:** Streamlines the deployment process.\n- **Easier Collaboration:** Provides a consistent environment for all developers.\n\n## OpenAPI Specification\n\nThere is an OpenAPI specification file (`openapi.yaml`) in the root directory that describes the API endpoints, request/response formats, and authentication methods. This can be used to generate client SDKs or documentation.\n\nTo view the API documentation, you can use tools like Swagger UI or Postman to import the `openapi.yaml` file. Or just go to the `/docs` endpoint of the deployed backend.\n\n## CI / CD with GitHub Actions\n\nThis project includes a GitHub Actions workflow for continuous integration and deployment. The workflow is defined in the `.github/workflows/workflow.yml` file and includes steps to:\n- Install dependencies for both the frontend and backend.\n- Run tests for both the frontend and backend.\n- Build the frontend and backend applications.\n- Deploy the applications to Vercel and Netlify.\n- Notify the team via email on successful deployments.\n- Notify the team via email on failed builds or tests.\n- Generate and upload artifacts for the frontend and backend builds.\n- Run linting checks for both the frontend and backend code.\n- _and more..._\n\nThis workflow ensures that every commit and pull request is tested and deployed automatically, providing a robust CI/CD pipeline.\n\nPlease ensure you have the necessary secrets configured in your GitHub repository for deployment (e.g, Vercel and Netlify tokens, etc.). Also, feel free to customize the workflow under [`.github/workflows/workflow.yml`](.github/workflows/workflow.yml) to suit your needs.\n\n## Testing\n\nThis project includes unit and integration tests with Jest for both the frontend and backend. To run the tests:\n\n- **Frontend:**  \n  Navigate to the `client` directory and run:\n\n  ```bash\n  npm test\n  ```\n  \n- **Backend:**  \n  Navigate to the `server` directory and run:\n\n  ```bash\n  npm test\n  ```\n\n## Contributing\n\n1. Fork the repository.\n2. Create your feature branch: `git checkout -b feature/your-feature-name`\n3. Commit your changes: `git commit -m 'Add some feature'`\n4. Push to the branch: `git push origin feature/your-feature-name`\n5. Open a Pull Request.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n## Contact\n\nIf you have any questions or suggestions, feel free to reach out to me:\n\n- **David Nguyen**\n  - [LinkedIn](https://www.linkedin.com/in/hoangsonw/)\n  - [GitHub](https://github.com/hoangsonww)\n  - [Email](mailto:hoangson091104@gmail.com)\n\n---\n\nThank you for checking out the AI Assistant Project! If you have any questions or feedback, feel free to reach out. Happy coding! 🚀\n\n[⬆️ Back to Top](#table-of-contents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoangsonww%2Fai-rag-assistant-chatbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhoangsonww%2Fai-rag-assistant-chatbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoangsonww%2Fai-rag-assistant-chatbot/lists"}