🎉 Complete AI-Enhanced University Portal - Ready for Production
✨ Major Features Added: - AI Chat with conversation memory and university-specific knowledge base - Multi-tenant university support with white-label capabilities - Professional admin interface for knowledge base management - Advanced database schema with Prisma ORM - Comprehensive documentation and guides - Modern Next.js 15 + React 19 architecture - Bilingual support (English/Arabic) - Role-based access control - Real-time chat interface with loading states 🔧 Technical Improvements: - Fixed all linter errors and TypeScript issues - Cleaned up codebase and removed legacy files - Added comprehensive .gitignore - Updated README with detailed setup instructions - Optimized database schema and migrations - Enhanced error handling and user experience 📚 Documentation: - AI Conversation Memory Guide - AI Enhancement Summary - Developer Guide - User Guide - Complete setup and deployment instructions 🚀 Ready for GitHub deployment and production use!
This commit is contained in:
Krikorios
@@ -0,0 +1,99 @@
|
||||
# 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**
|
||||
Reference in New Issue
Block a user