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

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

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

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

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