# 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:

```env
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

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

---

**Updated on July 13, 2025**