unai/docs/BRANCH_MANAGEMENT_GUIDE.md

Branch Management System Guide

Overview

The White-Label University Portal now supports both standalone university deployment and multi-branch university management. This system allows universities to:

1. Standalone Mode: Deploy as a single university with full independence
2. Multi-Branch Mode: Manage multiple campuses, centers, and branches under one parent university

Architecture

Database Schema

model University {
  id                String   @id @default(uuid())
  slug              String   @unique
  name              String
  shortName         String?
  domain            String?
  subdomain         String?
  
  // Branch Management
  isMultiBranch     Boolean  @default(false)
  parentUniversityId String?
  branchType        BranchType?
  
  // Configuration
  branding          Json
  contact           Json
  features          Json
  ai                Json
  status            UniversityStatus @default(SETUP)
  
  // Relationships
  parentUniversity  University? @relation("UniversityBranches", fields: [parentUniversityId], references: [id])
  branches          University[] @relation("UniversityBranches")
}

enum BranchType {
  MAIN
  CAMPUS
  CENTER
  BRANCH
  EXTENSION
  PARTNER
}

Branch Types

• MAIN: Primary campus/university (can have branches)
• CAMPUS: Physical campus location
• CENTER: Specialized center or institute
• BRANCH: Regional or satellite branch
• EXTENSION: Extension program or location
• PARTNER: Partner institution or collaborative program

Implementation

1. University Provider

The enhanced UniversityProvider now includes branch management capabilities:

interface UniversityContextType {
  university: University | null;
  branches: University[];
  parentUniversity: University | null;
  loading: boolean;
  error: string | null;
  refreshUniversity: () => Promise<void>;
  updateUniversity: (updates: Partial<University>) => Promise<void>;
  switchBranch: (branchId: string) => Promise<void>;
  isBranch: boolean;
  isMainCampus: boolean;
  canManageBranches: boolean;
}

2. Branch Management Hooks

// Main hook for university context
const { university, loading, error } = useUniversity();

// Branch management specific hook
const { branches, parentUniversity, isBranch, switchBranch } = useBranchManagement();

// Feature flags
const hasBranchManagement = useFeatureEnabled('branchManagement');

3. API Endpoints

Get University Branches

GET /api/universities/{slug}/branches

Create New Branch

POST /api/universities/{slug}/branches
Content-Type: application/json

{
  "name": "Dubai Campus",
  "shortName": "UTAS Dubai",
  "branchSlug": "utas-dubai",
  "branchType": "CAMPUS",
  "domain": "utas-dubai.edu.ae",
  "subdomain": "dubai"
}

Usage Scenarios

Scenario 1: Standalone University

A single university wants to deploy their portal independently:

// University configuration
{
  name: "University of Technology",
  slug: "utech",
  isMultiBranch: false,
  branchType: null,
  parentUniversityId: null
}

Features Available:

• Full university portal functionality
• Independent branding and content
• No branch management interface
• Single domain/subdomain

Scenario 2: Multi-Branch University

A university with multiple campuses wants centralized management:

// Parent University
{
  name: "University of Global Education",
  slug: "uge",
  isMultiBranch: true,
  branchType: "MAIN",
  parentUniversityId: null
}

// Branch Campus
{
  name: "UGE Dubai Campus",
  slug: "uge-dubai",
  isMultiBranch: false,
  branchType: "CAMPUS",
  parentUniversityId: "uge-parent-id"
}

Features Available:

• Branch management dashboard
• Shared content and branding options
• Independent branch configurations
• Branch switching interface

Scenario 3: University Network

Multiple universities want to share a platform:

// Each university is independent
{
  name: "University A",
  slug: "university-a",
  isMultiBranch: false,
  branchType: null,
  parentUniversityId: null
}

{
  name: "University B", 
  slug: "university-b",
  isMultiBranch: false,
  branchType: null,
  parentUniversityId: null
}

Components

1. Branch Selector

The BranchSelector component provides branch switching functionality:

import { BranchSelector } from '@/components/BranchManagement/BranchSelector';

// In your component
<BranchSelector className="ml-4" />

Features:

• Dropdown with available branches
• Visual indicators for branch types
• Quick branch switching
• Manage branches link (for admin users)

2. Main Navigation

The enhanced MainNavigation component adapts to branch context:

import { MainNavigation } from '@/components/Navigation/MainNavigation';

// Automatically shows branch context
<MainNavigation />

Features:

• Shows parent university name for branches
• Displays current branch name
• Includes branch selector for multi-branch universities
• Responsive mobile navigation

3. Branch Management Page

Admin interface for managing branches:

// Access via /admin/branches
<BranchesPage />

Features:

• List all branches
• Create new branches
• Edit branch configurations
• Delete branches
• Branch status management

Configuration

Feature Flags

Control branch management features per university:

features: {
  branchManagement: true,      // Enable branch management
  sharedContent: true,         // Share content between branches
  independentBranding: false,  // Allow independent branding per branch
}

Branding Inheritance

Branches can inherit branding from parent university:

// When creating a branch
branding: {
  primaryColor: parentUniversity.branding.primaryColor,
  secondaryColor: parentUniversity.branding.secondaryColor,
  logo: parentUniversity.branding.logo,
  favicon: parentUniversity.branding.favicon,
  theme: 'modern'
}

Content Sharing

Configure content sharing between branches:

// Shared content settings
features: {
  sharedContent: true,
  sharedPrograms: true,
  sharedKnowledgeBase: false,
  independentNews: true
}

Deployment Options

Option 1: Single University Deployment

# Deploy as standalone university
npm run build
npm run start

Use Case: Single university with one campus

Option 2: Multi-Branch University Deployment

# Deploy with branch management
npm run build
npm run start

Use Case: University with multiple campuses

Option 3: Multi-University Platform

# Deploy as platform for multiple universities
npm run build
npm run start

Use Case: SaaS platform serving multiple universities

Migration Guide

From Single University to Multi-Branch

1. Update Database Schema

   npx prisma migrate dev --name add_branch_management
   

2. Update University Configuration

   // Set existing university as main campus
   await prisma.university.update({
     where: { slug: 'existing-university' },
     data: { 
       isMultiBranch: true,
       branchType: 'MAIN'
     }
   });
   

3. Create Branches

   // Create new branches
   await prisma.university.create({
     data: {
       name: 'New Campus',
       slug: 'new-campus',
       parentUniversityId: 'existing-university-id',
       branchType: 'CAMPUS',
       isMultiBranch: false
     }
   });
   

From Multi-Branch to Standalone

1. Remove Branch Relationships

   // Update branches to be independent
   await prisma.university.updateMany({
     where: { parentUniversityId: 'parent-id' },
     data: { 
       parentUniversityId: null,
       isMultiBranch: false,
       branchType: null
     }
   });
   

2. Update Parent University

   await prisma.university.update({
     where: { id: 'parent-id' },
     data: { 
       isMultiBranch: false,
       branchType: null
     }
   });
   

Best Practices

1. Naming Conventions

• Slugs: Use consistent naming (e.g., utas-main, utas-dubai, utas-singapore)
• Domains: Follow pattern (e.g., utas.edu.om, dubai.utas.edu.om)
• Branch Types: Use appropriate types for clear organization

2. Content Strategy

• Shared Content: Use for policies, general information
• Branch-Specific Content: Use for local events, campus-specific information
• Branding: Inherit from parent but allow customization

3. User Management

• Admin Users: Can manage all branches
• Branch Users: Limited to their specific branch
• Content Permissions: Configure based on sharing requirements

4. Performance Considerations

• Caching: Cache branch-specific data separately
• Database Queries: Use proper indexing for branch relationships
• CDN: Configure branch-specific asset delivery

Troubleshooting

Common Issues

1. Branch Not Showing

   • Check isMultiBranch flag on parent university
   • Verify parentUniversityId relationship
   • Ensure branch status is 'ACTIVE'

2. Branch Switching Not Working

   • Check cookie settings
   • Verify API endpoint permissions
   • Ensure proper university context

3. Content Not Sharing

   • Check sharedContent feature flag
   • Verify content ownership settings
   • Review content isolation rules

Debug Commands

# Check database relationships
npx prisma studio

# Verify API endpoints
curl http://localhost:3000/api/universities/{slug}/branches

# Test branch switching
curl -X POST http://localhost:3000/api/universities/{branchId}

Future Enhancements

Planned Features

1. Advanced Branch Analytics

   • Branch-specific usage statistics
   • Cross-branch comparison reports
   • Performance metrics per branch

2. Branch Templates

   • Pre-configured branch setups
   • Quick branch creation wizards
   • Standardized configurations

3. Branch Collaboration

   • Inter-branch content sharing
   • Collaborative programs
   • Shared student services

4. Multi-Language Branch Support

   • Branch-specific language settings
   • Localized content per branch
   • Regional language preferences

This branch management system provides the flexibility to support both simple standalone universities and complex multi-branch institutions while maintaining the white-label capabilities of the platform.