unai/CHATBOT_SYSTEM_DOC.md

UTAS University Portal Chatbot System Documentation

Overview

The UTAS University Portal Chatbot ("University Assistant") is a multilingual AI-powered assistant designed to:

• Provide general university information to anonymous (logged-out) visitors.
• Offer personalized guidance based on user authentication and role when logged in.
• Support both English and Arabic using a hybrid rule-based knowledge search and LLM fallback.
• Integrate with OpenRouter (OpenAI-compatible) and/or Ollama local models (e.g., command-r7b-arabic).

Architecture

Frontend (ChatWidget.tsx)
    ↕
API Route (`/api/chat/route.ts`)
    ↕
Backend Bot Engine (`src/lib/chatbot.ts`)
    ↔
Knowledge Base (`src/lib/utasKnowledgeBase.ts`)
    ↔
User Context (AuthProvider)
    ↕
AI Provider (OpenRouter SDK / Ollama client)

Frontend

• ChatWidget: React component, toggles between general and mental-health modes.
• Surveys and escalation logic are built-in.
• Uses fetch to POST messages to /api/chat.
• User Context Integration: Automatically includes user role and profile data from AuthProvider when user is logged in.

API Layer (/api/chat)

• POST /api/chat: Accepts { message, mode?, history?, userContext? }, initializes UTASChatBot with API key from .env.local.
• GET /api/chat: Returns service status and supported features.

Bot Engine (UTASChatBot)

• Language Detection: Simple regex-based Arabic detection.
• Rule-based KB Search: Returns up to 3 relevant items from structured knowledge base.
• LLM Fallback: Configurable system prompts for OpenAI or Ollama.
• Personalized Responses: Adjusts responses based on user role and profile data.
• Ollama Integration: Falls back to local Ollama model if no OpenRouter API key.

Authentication & Personalization

1. Anonymous (Logged-out): Returns only publicly available course, admission, scholarship info. No user-specific data.
2. Authenticated: When user is logged in, passes user role and profile as part of request payload. Bot tailors responses (e.g., shows application status, next steps).

Personalization Implementation

• Frontend includes user.role and profile data from AuthProvider in /api/chat request.
• UTASChatBot.generateResponse accepts userContext parameter.
• System prompts are dynamically generated based on user role and context.
• Different handling for students, faculty, staff, and admin roles.

AI Provider Integration

• OpenRouter: Default via process.env.OPENROUTER_API_KEY.
• Ollama: Uses local model specified by MODEL_COMMAND_R7B if OpenRouter key is not available.

Configuration

Create a .env.local at project root:

OPENROUTER_API_KEY=sk-... (your credits)
OLLAMA_URL=http://localhost:11434
MODEL_COMMAND_R7B=command-r7b-arabic

Layout & UI Fixes

• Landing-page container elements updated with max-w-7xl, overflow-x-hidden, and responsive padding.
• Consistent margins maintained when switching between slides or tabs.

Testing

• Integration tests verify different response behaviors:
  • Anonymous chat returns only public information
  • Authenticated chat returns personalized responses based on user role
• Language switching (English/Arabic) works in all modes
• Ollama fallback activates when OpenRouter key is not available

Progress Tracker

• Create system-level docs (this file)
• Expose user context in frontend requests
• Extend API route to accept user context
• Update UTASChatBot for role-based prompts
• Integrate Ollama client as alternative provider
• Write tests for both anonymous and authenticated flows
• Fix landing-page layout out-of-margin issues
• QA and deploy

---

Updated on July 13, 2025