unai/docs/WHITE_LABEL_DOCUMENTATION.md

# White-Label University Portal Documentation

## 📋 Project Overview

**Current State**: UTAS (University of Tasmania) Oman campus portal  
**Target State**: Multi-tenant white-label university portal platform  
**Technology Stack**: Next.js 14, React 19, TypeScript, Tailwind CSS, Prisma, OpenRouter AI

## 🎯 White-Label Requirements

### Core Objectives
1. **Multi-University Support**: Serve multiple universities from single codebase
2. **Dynamic Branding**: University-specific logos, colors, and content
3. **Configurable Features**: Enable/disable features per university
4. **Scalable Architecture**: Support 10+ universities simultaneously
5. **Easy Onboarding**: Quick setup for new universities

### Business Goals
- **Revenue Model**: SaaS subscription for universities
- **Target Market**: Universities seeking modern, AI-powered portals
- **Competitive Advantage**: Advanced AI chatbot + comprehensive features
- **Time to Market**: 3-4 months for MVP

## 🏗️ Current Architecture Analysis

### ✅ Strengths
- Modern tech stack (Next.js 14, React 19)
- AI-powered bilingual chatbot
- Responsive design with Tailwind CSS
- Comprehensive university portal features
- TypeScript for type safety

### ❌ Limitations
- Hardcoded UTAS branding (200+ references)
- Static knowledge base
- Mock authentication system
- No admin interface
- Single-tenant architecture

## 📊 File Analysis & Cleanup Plan

### Files to Remove/Refactor

#### 1. UTAS-Specific Files
```
❌ src/app/page-enhanced-utas-oman.tsx (UTAS Oman specific)
❌ src/app/page-enhanced.tsx (UTAS specific)
❌ src/lib/utasKnowledgeBase.ts (Hardcoded UTAS data)
❌ src/lib/mockData.ts (UTAS-specific mock data)
❌ AI_Enhanced_UTAS_Portal_Presentation.pptx (Marketing material)
```

#### 2. Documentation Files to Archive
```
📁 docs/archive/
├── CHATBOT_SYSTEM_DOC.md (Move to docs/)
├── GITHUB-SETUP.md (Move to docs/)
├── NAVIGATION-TEST.md (Move to docs/)
└── TEST-USERS.md (Move to docs/)
```

#### 3. Test Files to Reorganize
```
📁 tests/
├── chatbot.test.ts (Keep, update for white-label)
├── integration/ (New directory)
└── e2e/ (New directory)
```

### Files to Create/Modify

#### 1. Configuration System
```
✅ src/config/
├── university.ts (University configuration interface)
├── branding.ts (Branding configuration)
├── features.ts (Feature flags)
└── ai.ts (AI configuration)
```

#### 2. Database Schema
```
✅ prisma/
├── schema.prisma (Add university tables)
├── migrations/ (Database migrations)
└── seeds/ (University-specific seeds)
```

#### 3. Admin Interface
```
✅ src/app/admin/
├── universities/ (University management)
├── content/ (Content management)
├── users/ (User management)
└── analytics/ (Analytics dashboard)
```

## 🗄️ Database Schema Design

### New Tables Required

```sql
-- University Configuration
CREATE TABLE universities (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  slug VARCHAR(50) UNIQUE NOT NULL,
  name VARCHAR(255) NOT NULL,
  short_name VARCHAR(100),
  domain VARCHAR(255),
  subdomain VARCHAR(100),
  branding_config JSONB,
  contact_config JSONB,
  features_config JSONB,
  ai_config JSONB,
  status ENUM('active', 'inactive', 'setup') DEFAULT 'setup',
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Academic Programs
CREATE TABLE academic_programs (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  university_id UUID REFERENCES universities(id),
  title VARCHAR(255) NOT NULL,
  title_ar VARCHAR(255),
  description TEXT,
  description_ar TEXT,
  level ENUM('undergraduate', 'postgraduate', 'phd'),
  duration VARCHAR(100),
  fees VARCHAR(100),
  entry_requirements TEXT,
  campus_locations JSONB,
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- University Content
CREATE TABLE university_content (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  university_id UUID REFERENCES universities(id),
  content_type ENUM('about', 'rankings', 'research', 'campus', 'news', 'events'),
  title VARCHAR(255) NOT NULL,
  title_ar VARCHAR(255),
  content TEXT,
  content_ar TEXT,
  metadata JSONB,
  is_published BOOLEAN DEFAULT false,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- AI Knowledge Base
CREATE TABLE ai_knowledge_base (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  university_id UUID REFERENCES universities(id),
  category VARCHAR(100),
  question VARCHAR(500),
  question_ar VARCHAR(500),
  answer TEXT,
  answer_ar TEXT,
  priority INTEGER DEFAULT 1,
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);
```

## 🔧 Implementation Phases

### Phase 1: Foundation (Weeks 1-2)
**Goal**: Establish white-label foundation

#### Tasks:
- [ ] **Database Schema**: Create new university tables
- [ ] **Configuration System**: Build university config interface
- [ ] **File Cleanup**: Remove UTAS-specific files
- [ ] **Basic Admin**: Create university management interface
- [ ] **Environment Setup**: Multi-environment configuration

#### Deliverables:
- ✅ Database migrations
- ✅ University configuration system
- ✅ Clean codebase (no UTAS references)
- ✅ Basic admin dashboard

### Phase 2: Content Management (Weeks 3-4)
**Goal**: Dynamic content system

#### Tasks:
- [ ] **Content Management**: Database-driven content system
- [ ] **Media Management**: Image and file upload system
- [ ] **Translation Interface**: Bilingual content management
- [ ] **Program Management**: Academic program CRUD operations
- [ ] **Knowledge Base**: Dynamic AI knowledge base

#### Deliverables:
- ✅ Content management dashboard
- ✅ Media upload system
- ✅ Translation tools
- ✅ Program management interface

### Phase 3: Multi-Tenant Architecture (Weeks 5-7)
**Goal**: Multi-university support

#### Tasks:
- [ ] **Route Structure**: University-specific routing
- [ ] **Data Isolation**: Multi-tenant data separation
- [ ] **Asset Management**: University-specific assets
- [ ] **Domain Management**: Subdomain and custom domain support
- [ ] **Deployment Automation**: Multi-university deployment

#### Deliverables:
- ✅ Multi-tenant routing system
- ✅ Data isolation mechanisms
- ✅ Asset management system
- ✅ Deployment automation

### Phase 4: Advanced Features (Weeks 8-10)
**Goal**: Production-ready features

#### Tasks:
- [ ] **Advanced AI**: University-specific chatbot training
- [ ] **Analytics**: Usage and performance metrics
- [ ] **API Development**: REST API for integrations
- [ ] **Security**: Multi-tenant security measures
- [ ] **Testing**: Comprehensive test suite

#### Deliverables:
- ✅ Advanced AI configuration
- ✅ Analytics dashboard
- ✅ REST API documentation
- ✅ Security audit report
- ✅ Test coverage report

### Phase 5: Launch Preparation (Weeks 11-12)
**Goal**: Production deployment

#### Tasks:
- [ ] **Performance Optimization**: Caching and optimization
- [ ] **Documentation**: User and developer documentation
- [ ] **Support System**: Help desk and support tools
- [ ] **Monitoring**: Application monitoring and alerting
- [ ] **Launch**: Production deployment and go-live

#### Deliverables:
- ✅ Performance benchmarks
- ✅ Complete documentation
- ✅ Support system
- ✅ Production monitoring
- ✅ Live platform

## 🎨 Branding & Design System

### Configuration Interface
```typescript
interface UniversityBranding {
  // Basic Information
  name: string;
  shortName: string;
  tagline: string;
  taglineAr?: string;
  
  // Visual Identity
  logo: {
    primary: string;
    secondary?: string;
    favicon: string;
  };
  
  // Color Palette
  colors: {
    primary: string;
    secondary: string;
    accent: string;
    background: string;
    surface: string;
    text: {
      primary: string;
      secondary: string;
    };
  };
  
  // Typography
  fonts: {
    primary: string;
    secondary?: string;
  };
  
  // Contact Information
  contact: {
    phone: string;
    email: string;
    address: string;
    website: string;
    socialMedia?: {
      facebook?: string;
      twitter?: string;
      linkedin?: string;
      instagram?: string;
    };
  };
}
```

### Feature Configuration
```typescript
interface UniversityFeatures {
  // Core Features
  studentPortal: boolean;
  facultyPortal: boolean;
  researchPortal: boolean;
  internationalStudents: boolean;
  
  // AI Features
  aiChatbot: boolean;
  aiKnowledgeBase: boolean;
  aiAccessibility: boolean;
  
  // Language Support
  languages: string[];
  rtlSupport: boolean;
  
  // Integrations
  integrations: {
    email: boolean;
    calendar: boolean;
    payment: boolean;
    analytics: boolean;
  };
}
```

## 🤖 AI Configuration System

### Chatbot Configuration
```typescript
interface AIConfig {
  // Provider Settings
  provider: 'openrouter' | 'ollama' | 'openai';
  apiKey?: string;
  model: string;
  
  // University Context
  universityContext: {
    name: string;
    location: string;
    specializations: string[];
    achievements: string[];
    programs: string[];
  };
  
  // Response Customization
  personality: {
    tone: 'professional' | 'friendly' | 'formal';
    language: string[];
    expertise: string[];
  };
  
  // Knowledge Base
  knowledgeBase: {
    autoUpdate: boolean;
    sources: string[];
    categories: string[];
  };
}
```

## 📈 Analytics & Monitoring

### Key Metrics
1. **User Engagement**
   - Daily/Monthly active users
   - Page views and session duration
   - Chatbot interactions
   - Feature usage

2. **Performance**
   - Page load times
   - API response times
   - Error rates
   - Uptime

3. **Business Metrics**
   - University onboarding time
   - Customer satisfaction scores
   - Revenue per university
   - Churn rate

### Monitoring Tools
- **Application Monitoring**: Sentry for error tracking
- **Performance Monitoring**: Vercel Analytics
- **User Analytics**: Google Analytics 4
- **Database Monitoring**: Prisma Studio + custom dashboards

## 🔒 Security & Compliance

### Multi-Tenant Security
1. **Data Isolation**: Strict university data separation
2. **Authentication**: Role-based access control
3. **API Security**: Rate limiting and authentication
4. **Data Encryption**: At rest and in transit

### Compliance Requirements
1. **GDPR**: European data protection
2. **FERPA**: Educational records privacy (US)
3. **Local Regulations**: Country-specific requirements
4. **Accessibility**: WCAG 2.1 AA compliance

## 🚀 Deployment Strategy

### Environment Structure
```
Development: dev.university-portal.com
Staging: staging.university-portal.com
Production: university-portal.com
```

### University Domains
```
Option 1: Subdomains
- university1.university-portal.com
- university2.university-portal.com

Option 2: Custom Domains
- university1.edu
- university2.edu
```

### Infrastructure
- **Hosting**: Vercel (Next.js optimized)
- **Database**: Supabase (PostgreSQL)
- **File Storage**: Supabase Storage
- **CDN**: Vercel Edge Network
- **Monitoring**: Sentry + Vercel Analytics

## 💰 Business Model

### Pricing Tiers

#### Basic Plan ($299/month)
- Single university
- Basic features
- Email support
- 10GB storage

#### Professional Plan ($599/month)
- Up to 3 universities
- Advanced features
- Priority support
- 50GB storage
- Custom branding

#### Enterprise Plan ($1,299/month)
- Unlimited universities
- All features
- Dedicated support
- Unlimited storage
- Custom integrations
- SLA guarantee

### Revenue Projections
- **Year 1**: 10 universities = $60,000 ARR
- **Year 2**: 50 universities = $300,000 ARR
- **Year 3**: 100 universities = $600,000 ARR

## 📚 Documentation Structure

### User Documentation
```
docs/
├── getting-started/
│   ├── quick-start.md
│   ├── university-setup.md
│   └── first-university.md
├── user-guides/
│   ├── admin-dashboard.md
│   ├── content-management.md
│   ├── user-management.md
│   └── analytics.md
├── features/
│   ├── ai-chatbot.md
│   ├── student-portal.md
│   ├── research-portal.md
│   └── international-students.md
└── troubleshooting/
    ├── common-issues.md
    ├── support-contacts.md
    └── faq.md
```

### Developer Documentation
```
docs/
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── webhooks.md
├── development/
│   ├── setup.md
│   ├── architecture.md
│   ├── database.md
│   └── deployment.md
├── integrations/
│   ├── third-party.md
│   ├── custom-features.md
│   └── api-examples.md
└── contributing/
    ├── code-style.md
    ├── testing.md
    └── pull-requests.md
```

## 🎯 Success Criteria

### Technical Success
- [ ] Zero UTAS references in codebase
- [ ] Multi-tenant architecture working
- [ ] 99.9% uptime
- [ ] <2 second page load times
- [ ] 100% test coverage for critical paths

### Business Success
- [ ] 5 universities onboarded in first 3 months
- [ ] $15,000 MRR by month 6
- [ ] 90% customer satisfaction score
- [ ] 0% churn rate in first 6 months
- [ ] 3 case studies published

### User Success
- [ ] <30 minutes university setup time
- [ ] <5 minutes content update time
- [ ] 95% chatbot satisfaction rate
- [ ] 80% feature adoption rate

---

**Last Updated**: January 2025  
**Version**: 1.0  
**Status**: Planning Phase