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

```prisma
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:

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

```typescript
// 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
```http
GET /api/universities/{slug}/branches
```

#### Create New Branch
```http
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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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:

```tsx
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:

```tsx
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:

```tsx
// 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:

```typescript
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:

```typescript
// 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:

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

## Deployment Options

### Option 1: Single University Deployment

```bash
# Deploy as standalone university
npm run build
npm run start
```

**Use Case:** Single university with one campus

### Option 2: Multi-Branch University Deployment

```bash
# Deploy with branch management
npm run build
npm run start
```

**Use Case:** University with multiple campuses

### Option 3: Multi-University Platform

```bash
# 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**
   ```bash
   npx prisma migrate dev --name add_branch_management
   ```

2. **Update University Configuration**
   ```typescript
   // Set existing university as main campus
   await prisma.university.update({
     where: { slug: 'existing-university' },
     data: { 
       isMultiBranch: true,
       branchType: 'MAIN'
     }
   });
   ```

3. **Create Branches**
   ```typescript
   // 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**
   ```typescript
   // Update branches to be independent
   await prisma.university.updateMany({
     where: { parentUniversityId: 'parent-id' },
     data: { 
       parentUniversityId: null,
       isMultiBranch: false,
       branchType: null
     }
   });
   ```

2. **Update Parent University**
   ```typescript
   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

```bash
# 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.