RAG-based Educational Assistant Chatbot

An end-to-end chatbot that assists:

• Applicants coming to study in Iran
• Students in Iran seeking to study abroad

It combines a Nuxt 3 frontend, a Node.js/Express backend, and a Python FastAPI RAG service powered by lightweight Sentence Transformers to retrieve curated, verified country-specific guidance. The system prioritizes grounded answers using RAG to minimize hallucinations.

Architecture at a glance

• front/ — Nuxt 3 single-page app with a chat UI and i18n-friendly layout
• backend/ — Express API gateway that:
  • Uses OpenAI or Gemini to generate responses
  • Optionally enables RAG mode to fetch relevant chunks from the RAG API
  • Persists chat history in MongoDB
• RAG/ — FastAPI service that:
  • Builds embeddings with Sentence Transformers (LaBSE by default)
  • Stores chunked text and embeddings in MongoDB
  • Exposes /send and /receive endpoints secured by a token header

Screenshots

---

Prerequisites

• Node.js 18+ and npm
• Python 3.10+
• MongoDB (local or Atlas connection string)
• OpenAI API key (required for query expansion in RAG and for backend OpenAI mode) or Gemini API key (if using Gemini in backend)

---

Environment configuration

All three components use .env files. Do not commit secrets. See the provided .envexample files in front/ and RAG/ for guidance.

Frontend (front/.env)

# API base URL of the backend
VITE_API_URL=http://localhost:5100

# UI language and direction
VITE_APP_LANGUAGE=en
VITE_APP_DIRECTION=ltr

# Conversation direction used by backend logic: "send" (going abroad) or "receive" (coming to Iran)
VITE_DIRECTION=send

# A stable user id to load/save chat history
VITE_USER_ID=local-dev-user

Backend (backend/.env)

# Server
PORT=5100
NODE_ENV=development

# Persistence
MONGODB_URI=mongodb://localhost:27017/elmino

# LLM provider for response generation
# AI_PROVIDER=OPENAI or GEMINI
AI_PROVIDER=OPENAI
OPENAI_API_KEY=sk-...
# If using Gemini instead of OpenAI
# GEMINI_API_KEY=...

# Response strategy: RAG uses RAG API, PROMPT bypasses RAG
MODE=RAG

# RAG API integration
QUERY_API_URL=http://localhost:8001
RAG_API_TOKEN=dev-token

Notes

• The backend exposes:
  • POST /chatbot — send a message { message, direction, userId }
  • POST /chatbot/history — fetch last messages { direction, userId }
  • DELETE /chatbot — delete all history { direction, userId }
• In RAG mode, the backend calls the RAG API at QUERY_API_URL with header X-Token: RAG_API_TOKEN.

RAG service (RAG/.env)

MONGODB_URI=mongodb://localhost:27017/elmino_rag
API_PORT=8001
API_HOST=127.0.0.1
API_TOKEN=dev-token

# Used for query expansion prompts inside the RAG service
OPENAI_API_KEY=sk-...

Important

• Ensure API_TOKEN here matches RAG_API_TOKEN in backend/.env.
• For Docker, set API_PORT=3010 if you use the included RAG/docker-compose.yml mapping 3010:3010.

---

Install and run (local development)

Open three terminals or run sequentially.

1) RAG service

cd RAG
python -m venv .venv
. .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .envexample .env   # fill values
python rag_api.py     # serves on API_HOST:API_PORT (default 0.0.0.0:8000; set 8001 in .env)

Endpoints (with X-Token: API_TOKEN):

• POST /send/query and POST /receive/query
• GET /send/health and GET /receive/health
• POST /send/reload and POST /receive/reload — rebuild chunks/embeddings

Request body for /query:

{
  "query": "visa requirements for Germany",
  "reload": false,
  "memory": "recent chat context text"
}

2) Backend API

cd backend
npm install
cp .envexample .env   # create if not present and fill values
npm run dev           # or: npm start

The backend reads PORT from .env. The frontend example uses http://localhost:5100.

3) Frontend (Nuxt 3)

cd front
npm install
cp .envexample .env   # fill values or adjust VITE_API_URL
npm run dev           # default: http://localhost:3000

Open the app in your browser and start chatting. The UI language and text direction are controlled by VITE_APP_LANGUAGE and VITE_APP_DIRECTION. The chat mode (send or receive) is controlled by VITE_DIRECTION.

---

Docker

Docker files are provided for the backend and RAG services.

Backend

cd backend
docker build -t chatbot .
docker network create persiastudy || true
docker compose up -d

This maps 3012:3012 by default (see backend/docker-compose.yml). If you rely on Docker for backend in dev, set VITE_API_URL=http://localhost:3012 in the frontend.

RAG

cd RAG
docker build -t chatbotrag .
docker network create persiastudy || true
docker compose up -d

The compose maps 3010:3010. Ensure API_PORT=3010 inside RAG/.env so the FastAPI service listens on the mapped port.

---

Data and prompts

• Backend prompt templates: backend/data/prompt-base/
• Backend RAG base prompt handles send/receive modes: backend/data/RAG-base/
• RAG datasets (curated text): RAG/data/Send/, RAG/data/Receive/
• Query expansion prompts: RAG/data/Prompts/

To refresh RAG chunks/embeddings after changing data, call:

curl -X POST \
  -H "X-Token: $API_TOKEN" \
  http://localhost:8001/send/reload

Debug artifacts are written by the RAG service for inspection:

• RAG/debug_similarity_scores.txt
• RAG/processors/* may write debug_chunks.txt during chunking

---

Switching embedding models

The RAG service currently loads sentence-transformers/LaBSE in RAG/rag_utils.py. You may switch to a lighter model (e.g., all-MiniLM-L6-v2) by editing the model load line and reloading the service.

---

Troubleshooting

• CORS: the backend enables CORS for common dev ports (3000/5173/3007). Ensure your frontend uses one of those origins or adjust the CORS config in backend/server.js.
• Ports: keep front VITE_API_URL aligned with backend PORT. Keep backend QUERY_API_URL aligned with RAG API_PORT.
• MongoDB connectivity: both backend and RAG use MONGODB_URI. Verify credentials and IP allowlists when using Atlas.

---

Scripts

Backend

npm run dev    # nodemon
npm start      # node server.js
npm test       # mocha tests/*

Frontend

npm run dev
npm run build
npm run preview

RAG

python rag_api.py

---