Skip to content

Home

Jump to bottom
dav nguyxn edited this page Sep 30, 2025 · 1 revision

AI-RAG Assistant Chatbot (“Lumina”) — Confluence/Wiki Page

Last updated: Sep 30, 2025
Owner: David Nguyen (repo: hoangsonww/AI-RAG-Assistant-Chatbot)

1) Overview

Lumina is a full-stack RAG-powered chatbot that answers questions about David Nguyen or general topics. It pairs a modern React/MUI frontend with an Express/TypeScript backend, adds JWT authentication, and uses Retrieval-Augmented Generation (RAG) via LangChain and Pinecone to ground LLM responses in a curated knowledge base. Logged-in users can save, search, and rename conversations; guests can chat without persistence.

Live apps

  • Frontend: https://lumina-david.vercel.app

  • Backend + Swagger: https://ai-assistant-chatbot-server.vercel.app

  • Backup frontend: https://lumina-ai-chatbot.netlify.app

Key Capabilities

  • Real-time chat with markdown rendering

  • RAG over personal knowledge base (Pinecone vector DB)

  • Auth (signup/login/reset) with JWT

  • Conversation CRUD + search (MongoDB via Mongoose)

  • Guest mode (ephemeral conversations)

  • Light/Dark themes, responsive UI, polished animations

  • CI/CD via GitHub Actions (deploy to Vercel/Netlify)

  • OpenAPI spec + Swagger docs

2) Architecture at a Glance

[ User ] 
   │  (browser)
   ▼
[ Frontend: React + MUI + TS ]
   │  REST (HTTPS)
   ▼
[ Backend: Express + TS ]
   ├─ Auth (JWT)
   ├─ Conversations API
   ├─ Chat API (LLM + RAG orchestration w/ LangChain)
   │
   ├─ MongoDB (Users, Conversations)
   └─ Pinecone (Vectors: knowledge chunks)
            ▲
            │  indexer script (storeKnowledge.ts / npm run store)
            └─ Knowledge sources (docs, notes, etc.)

RAG loop (high-level)

  1. Embed & store knowledge in Pinecone (storeKnowledge.ts).

  2. Retrieve top-k chunks from Pinecone for a user query (cosine similarity).

  3. Augment the prompt with retrieved context (LangChain).

  4. Generate an answer via LLM (OpenAI/Gemini).

  5. Persist messages to MongoDB for authenticated users; use ephemeral storage for guests.

3) Repository Structure

AI-RAG-Assistant-Chatbot/
├── client/                     # React + TS + MUI application
│   ├── src/
│   │   ├── components/         # Navbar, Sidebar, ChatArea
│   │   ├── pages/              # Landing, Home, Login, Signup, ForgotPassword, 404
│   │   ├── services/api.ts     # API client
│   │   ├── theme.ts            # Light/Dark themes
│   │   └── types/              # conversation.d.ts, user.d.ts
│   ├── Dockerfile, docker-compose.yml, tsconfig.json, package.json
│
├── server/                     # Express + TS backend
│   └── src/
│       ├── server.ts           # App bootstrap
│       ├── routes/             # auth.ts, conversations.ts, chat.ts
│       ├── models/             # User.ts, Conversation.ts
│       ├── middleware/         # auth.ts (JWT guard)
│       ├── services/           # authService.ts
│       ├── utils/              # ephemeralConversations.ts
│       └── scripts/            # storeKnowledge.ts (RAG indexer)
│   ├── Dockerfile, docker-compose.yml, tsconfig.json, package.json
│
├── openapi.yaml                # API contract (importable into Swagger/Postman)
├── docker-compose.yml          # Root compose for local dev
├── .github/workflows/          # CI/CD (build, test, deploy)
├── Jenkinsfile                 # (legacy/optional)
├── README.md, LICENSE, CITATION.cff
└── .env.example                # Example server env

4) Technology Stack

  • Frontend: React + TypeScript, Material UI (MUI)

  • Backend: Node.js, Express, TypeScript

  • Database: MongoDB (Mongoose)

  • Vector DB: Pinecone (k-NN cosine similarity)

  • RAG/Orchestration: LangChain

  • LLMs: OpenAI / Google Gemini (configurable)

  • Auth: JWT + middleware

  • Infra/Delivery: Vercel (FE), Netlify (FE backup), Vercel (BE)

  • Docs: OpenAPI + Swagger

  • CI/CD: GitHub Actions (install → test → build → deploy; artifacts, linting)

  • Containers: Docker, docker-compose

  • Testing: Jest (FE + BE)

  • Misc: Python/Jupyter for experiments (optional)

5) Environments & Configuration

Environment Variables (server)

Create server/.env (see .env.example) with:

PORT=5000
MONGODB_URI=mongodb://localhost:27017/ai-assistant
JWT_SECRET=replace_with_a_strong_secret
GOOGLE_AI_API_KEY=your_google_ai_api_key_here
AI_INSTRUCTIONS="System prompt for the assistant"
PINECONE_API_KEY=your_pinecone_api_key_here
PINECONE_INDEX_NAME=your_pinecone_index_name_here

Notes

  • JWT_SECRET must be long and random; rotate if leaked.

  • AI_INSTRUCTIONS holds your system prompt (persona/guardrails).

  • Ensure Pinecone index (dimension/metric) matches your embedding model.

Environment Variables (client)

Create client/.env (if not already present):

REACT_APP_API_BASE_URL=http://localhost:5000

Update this value to the deployed backend URL in hosted environments.

6) Local Development

Prerequisites

  • Node 18+ / npm

  • Docker (optional, recommended)

  • MongoDB (local or Docker)

  • Pinecone account & index

Quick Start (no Docker)

Backend

git clone https://github.com/hoangsonww/AI-RAG-Assistant-Chatbot.git
cd AI-RAG-Assistant-Chatbot/server
npm install
# 1) Prepare .env (see above)
# 2) (One-time) index your knowledge into Pinecone:
npm run store           # or: npx ts-node src/scripts/storeKnowledge.ts
# 3) Run the API:
npm run dev             # ts-node + nodemon

Frontend

cd ../client
npm install
npm start               # http://localhost:3000

Dockerized Dev

From repo root:

docker-compose up --build

This brings up the FE and BE services as defined in root docker-compose.yml.
Edit .env to point FE → BE service hostname within the compose network if needed.

7) Data Model (high-level)

The exact schemas live in server/src/models. Below is a typical structure to guide usage and API expectations.

User

  • email (unique), passwordHash (bcrypt), name?

  • createdAt, updatedAt

  • emailVerified? or verification helper endpoints

Conversation

  • userId (ref User; omitted for guest)

  • title

  • messages[] of { role: 'user' | 'assistant', content: string, ts }

  • createdAt, updatedAt

Ephemeral Conversations

  • Utility (utils/ephemeralConversations.ts) handles non-authenticated chat state without DB writes.

8) API Reference (OpenAPI + Highlights)

OpenAPI: openapi.yaml (repo root). Import into Swagger UI/Postman.
Deployed Swagger: at the backend host (e.g., /docs).

Auth

  • POST /api/auth/signup — create account
    Body: { email, password, name? }
    Returns: { token, user }

  • POST /api/auth/login — authenticate
    Body: { email, password } → { token, user }

  • GET /api/auth/verify-email?email=<addr> — email existence check

  • POST /api/auth/reset-password — start/reset flow (implementation depends on env)

Example

curl -X POST "$API/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"me@example.com","password":"secret"}'

Use Authorization: Bearer <token> for subsequent protected requests.

Conversations (JWT required)

  • POST /api/conversations — create new conversation
    Body: { title? } → { conversation }

  • GET /api/conversations — list all for user

  • GET /api/conversations/:id — get by id

  • PUT /api/conversations/:id — rename
    Body: { title }

  • GET /api/conversations/search/:query — title/content search

  • DELETE /api/conversations/:id — delete

Chat

  • POST /api/chat — send a user message and get AI response
    Body: { message: string, conversationId?: string }
    Returns: { reply, conversationId? }

    • Authenticated users: message persisted to conversation

    • Guests: handled via ephemeral store

9) RAG: Indexing & Retrieval

Indexing Knowledge (one-time or as needed)

# From server/:
npm run store
# or
npx ts-node src/scripts/storeKnowledge.ts

  • Reads your knowledge sources (implementation specific)

  • Splits/embeds documents

  • Upserts vectors into Pinecone (PINECONE_INDEX_NAME)

Tip: Re-run after updating the knowledge base.

Retrieval & Generation (runtime)

  1. Embed incoming user query.

  2. Pinecone similarity search (cosine) → top-k chunks.

  3. Assemble prompt (system instructions + retrieved context + user query).

  4. Call configured LLM (OpenAI/Gemini).

  5. Stream/return markdown answer; persist if authenticated.

10) Frontend UX Notes

  • Pages: Landing, Home (chat), Login, Signup, Forgot Password, 404

  • Components: Navbar, Sidebar (collapsible, lists conversations), ChatArea

  • Theme: Light/Dark with localStorage persistence

  • Guest Mode: Skip auth; ephemeral conversations only

11) CI/CD

GitHub Actions (recommended)

Workflow in .github/workflows/:

  • Install deps (client & server)

  • Lint, Jest tests

  • Build apps

  • Deploy:

    • FE → Vercel (primary) + Netlify (backup)

    • BE → Vercel

  • Artifacts upload, notifications on success/failure

Required secrets (examples): VERCEL_TOKEN, VERCEL_PROJECT_ID_(client/server), NETLIFY_AUTH_TOKEN, etc., plus runtime env for both apps. Configure in Repo Settings → Secrets and variables → Actions.

Jenkinsfile

Present for legacy/alt CI; prefer GitHub Actions unless org mandates Jenkins.

12) Deployment Runbook

  1. Prepare secrets in Vercel/Netlify dashboards:

    • Server: MONGODB_URI, JWT_SECRET, PINECONE_*, AI_INSTRUCTIONS, GOOGLE_AI_API_KEY

    • Client: REACT_APP_API_BASE_URL

  2. Trigger a release by merging to the main branch.

  3. Verify:

    • Backend health: open /docs and test /api/auth/login with a test user.

    • Frontend health: load / and /chat.

  4. Smoke test RAG:

    • Ask a question covered by the knowledge base; verify grounded response.

Rollback: Revert the commit or redeploy a prior successful build from Vercel/Netlify dashboards.

13) Security & Privacy

  • JWT: Signed with JWT_SECRET. Store tokens only in memory or secure storage on the client; avoid localStorage if possible.

  • Password hashing: Use bcrypt (or argon2) server-side.

  • CORS: Restrict origins in production.

  • PII: User emails are stored; conversation content may include sensitive data—ensure your privacy notice covers this.

  • Rate limiting: Recommended for /api/chat and auth routes.

  • Secrets management: Use platform secret managers; never commit secrets.

  • License: MIT (see LICENSE).

14) Testing

Frontend

cd client
npm test

Backend

cd server
npm test

Add integration tests for:

  • Auth flow (signup/login/jwt guard)

  • Conversation CRUD

  • Chat happy path + RAG retrieval stubs/mocks

Clone this wiki locally