# Admin Menu - Role-Based Access Control

## Overview
The admin sidebar menu is organized into logical sections and implements granular role-based access control. Menu items are dynamically shown/hidden based on the logged-in user's role and permissions.

---

## 📋 Menu Structure

### 1. **Overview Section**
Always visible to all admin users.

| Menu Item | Icon | Available To |
|-----------|------|--------------|
| Dashboard | 📊 | All admin users |

**Purpose:** Central hub for quick stats and recent activity

---

### 2. **Content Management Section**
Visible to communication staff and content creators.

| Menu Item | Icon | Available To |
|-----------|------|--------------|
| News Articles | 📰 | Administrator, Communications Manager, Senior Communications Officer, Content Writer, Social Media Specialist |
| Events | 📅 | Administrator, Communications Manager, Senior Communications Officer, Content Writer, Events Coordinator |
| Pages | 📄 | Administrator, Communications Manager, Senior Communications Officer, Content Writer |
| News Ticker | 📢 | Administrator, Communications Manager, Senior Communications Officer |
| Media Library | 🖼️ | Administrator, Communications Manager, Senior Communications Officer, Content Writer, Graphic Designer, Social Media Specialist |

**Purpose:** Create and manage website content

**Section Visibility:** Only shown if user has at least one content management role

---

### 3. **User Management Section**
Restricted to administrators and managers only.

| Menu Item | Icon | Available To |
|-----------|------|--------------|
| Users | 👥 | Administrator, Communications Manager |
| Roles & Permissions | 🛡️ | Administrator only |
| Departments | 🏢 | Administrator, Communications Manager |

**Purpose:** Manage system users, roles, and organizational structure

**Section Visibility:** Only shown to Administrators and Communications Managers

---

### 4. **Analytics & Monitoring Section**
For administrators and senior staff to monitor system performance.

| Menu Item | Icon | Available To |
|-----------|------|--------------|
| Analytics | 📊 | Administrator, Communications Manager, Senior Communications Officer |
| Audit Logs | 📋 | Administrator, Communications Manager |

**Purpose:** Monitor website traffic, user activity, and system logs

**Section Visibility:** Only shown to management and senior staff

---

### 5. **System Administration Section**
Restricted to top-level administrators only.

| Menu Item | Icon | Available To |
|-----------|------|--------------|
| Settings | ⚙️ | Administrator, Communications Manager |

**Purpose:** Configure system-wide settings (email, SMS, security)

**Section Visibility:** Only shown to Administrators and Communications Managers

---

## 👤 Access Matrix by Role

### **ADMINISTRATOR**
Full system access.
```
✅ Dashboard
✅ News Articles
✅ Events
✅ Pages
✅ News Ticker
✅ Media Library
✅ Users
✅ Roles & Permissions
✅ Departments
✅ Analytics
✅ Audit Logs
✅ Settings
```

---

### **COMMUNICATIONS_MANAGER**
Department head with management capabilities.
```
✅ Dashboard
✅ News Articles
✅ Events
✅ Pages
✅ News Ticker
✅ Media Library
✅ Users
❌ Roles & Permissions (Admin only)
✅ Departments
✅ Analytics
✅ Audit Logs
✅ Settings
```

---

### **SENIOR_COMMUNICATIONS_OFFICER**
Senior staff with content and analytics access.
```
✅ Dashboard
✅ News Articles
✅ Events
✅ Pages
✅ News Ticker
✅ Media Library
❌ Users
❌ Roles & Permissions
❌ Departments
✅ Analytics
❌ Audit Logs
❌ Settings
```

---

### **CONTENT_WRITER**
Content creation and editing.
```
✅ Dashboard
✅ News Articles
✅ Events
✅ Pages
❌ News Ticker
✅ Media Library
❌ Users
❌ Roles & Permissions
❌ Departments
❌ Analytics
❌ Audit Logs
❌ Settings
```

---

### **SOCIAL_MEDIA_SPECIALIST**
Social media content management.
```
✅ Dashboard
✅ News Articles
❌ Events
❌ Pages
❌ News Ticker
✅ Media Library
❌ Users
❌ Roles & Permissions
❌ Departments
❌ Analytics
❌ Audit Logs
❌ Settings
```

---

### **GRAPHIC_DESIGNER**
Media and visual content management.
```
✅ Dashboard
❌ News Articles
❌ Events
❌ Pages
❌ News Ticker
✅ Media Library
❌ Users
❌ Roles & Permissions
❌ Departments
❌ Analytics
❌ Audit Logs
❌ Settings
```

---

### **EVENTS_COORDINATOR**
Events planning and management.
```
✅ Dashboard
❌ News Articles
✅ Events
❌ Pages
❌ News Ticker
✅ Media Library
❌ Users
❌ Roles & Permissions
❌ Departments
❌ Analytics
❌ Audit Logs
❌ Settings
```

---

### **STAFF** (Basic User)
Minimal access - typically dashboard only.
```
✅ Dashboard
❌ All other sections
```

---

## 🔐 Security Implementation

### Role-Based Access Control (RBAC)
```typescript
interface NavItem {
  name: string
  href: string
  icon: Component
  roles?: string[]        // Which roles can see this item
  permissions?: string[]  // Alternative: specific permissions
}
```

### Access Check Logic
```typescript
const canAccessItem = (item: NavItem): boolean => {
  // No restrictions = everyone can access
  if (!item.roles || item.roles.length === 0) {
    return true
  }

  // Check if user's role is allowed
  const hasRole = item.roles.includes(userRole)

  // Check permissions if specified
  if (item.permissions && item.permissions.length > 0) {
    const hasPermission = item.permissions.some(perm => 
      userPermissions.includes(perm)
    )
    return hasRole || hasPermission
  }

  return hasRole
}
```

### Section-Level Access
```typescript
const canAccessSection = (section: NavSection): boolean => {
  // If no roles specified, show section
  if (!section.roles || section.roles.length === 0) {
    return true
  }

  // Check if user's role allows section access
  return section.roles.includes(userRole)
}
```

---

## 🎨 UI Features

### Collapsible Sections
- Users can collapse/expand menu sections
- State persists during session
- Chevron icons indicate collapsed state
- Click section header to toggle

### Active State Indication
- Current page highlighted with primary color
- Shadow effect on active menu item
- Text color changes on hover

### Role Badge Display
- Shows user's current role at bottom of sidebar
- Truncates long role names
- Shield icon for visual clarity

### Responsive Design
- Fixed sidebar on desktop
- Collapsible on mobile (to be implemented)
- Scrollable if content exceeds viewport

---

## 📊 Menu Item Categories

### **Primary Navigation** (Always Visible)
- Dashboard

### **Content Operations** (Content Creators)
- News Articles
- Events  
- Pages
- News Ticker
- Media Library

### **Administrative Operations** (Management)
- Users
- Roles & Permissions
- Departments

### **Monitoring Operations** (Senior Staff)
- Analytics
- Audit Logs

### **System Operations** (Administrators)
- Settings

---

## 🔄 Dynamic Behavior

### Show/Hide Logic
1. **User logs in** → Role extracted from JWT token
2. **Menu renders** → Each section evaluated
3. **Section check** → Is user's role in allowed roles?
4. **Item check** → For each item in visible section, check role
5. **Render** → Only show accessible items
6. **Empty section** → Hide section if no items visible

### Example Flow
```
User: Content Writer
Role: CONTENT_WRITER

Section: Content Management
  ✅ Show section (role included)
  Items:
    ✅ News Articles (role included)
    ✅ Events (role included)
    ✅ Pages (role included)
    ❌ News Ticker (role not included)
    ✅ Media Library (role included)

Section: User Management
  ❌ Hide section (role not included)

Result: User sees Content Management section with 4 items
```

---

## 🛠️ Configuration

### Adding a New Menu Item
```typescript
{
  name: 'New Feature',
  href: '/admin/new-feature',
  icon: IconComponent,
  roles: ['ADMINISTRATOR', 'COMMUNICATIONS_MANAGER'],
  permissions: ['MANAGE_FEATURE'], // Optional
}
```

### Adding a New Section
```typescript
{
  title: 'New Section',
  items: [
    // ... menu items
  ],
  roles: ['ADMINISTRATOR'], // Who can see this section
}
```

### Updating Role Access
Edit the `roles` array for any menu item to grant/revoke access.

---

## 🎯 Best Practices

### When to Use Role-Based Access
- ✅ Feature requires specific authority level
- ✅ Data is sensitive or confidential
- ✅ Action affects other users or system
- ✅ Compliance or audit requirements

### When to Use Permission-Based Access
- ✅ More granular control needed
- ✅ Custom role combinations required
- ✅ Temporary access grants needed
- ✅ Feature flags or A/B testing

### Menu Organization Guidelines
1. **Group related items** into logical sections
2. **Order by frequency** of use (most used at top)
3. **Limit section size** to 5-7 items max
4. **Use clear labels** that describe function
5. **Consistent icons** across similar functions

---

## 📱 Responsive Considerations

### Desktop (1024px+)
- Fixed sidebar visible
- All sections expanded by default
- Hover effects enabled

### Tablet (768px - 1023px)
- Collapsible sidebar
- Hamburger menu toggle
- Overlay on content when open

### Mobile (<768px)
- Full-screen overlay menu
- Tap to expand sections
- Swipe to close

---

## 🔍 Testing Access Control

### Test Cases
1. **Login as each role** → Verify correct menu items shown
2. **Navigate to restricted page** → Should redirect or show 403
3. **Modify role in localStorage** → Menu should update
4. **Check empty sections** → Should be hidden
5. **Collapsed sections** → Should remember state

### Manual Testing Checklist
```
[ ] Administrator sees all items
[ ] Communications Manager sees management items
[ ] Content Writer sees only content items
[ ] Social Media Specialist sees limited content items
[ ] Staff sees only dashboard
[ ] Sections with no items are hidden
[ ] Active page highlighted correctly
[ ] Role badge displays correctly
[ ] Collapse/expand works
[ ] Help section always visible
```

---

## 🚀 Future Enhancements

### Planned Features
- [ ] Custom permission combinations
- [ ] User-specific menu customization
- [ ] Favorite/pinned items
- [ ] Recent items quick access
- [ ] Notification badges on menu items
- [ ] Keyboard shortcuts
- [ ] Multi-level nested menus
- [ ] Search menu items

### Advanced Access Control
- [ ] Time-based access (business hours only)
- [ ] Location-based restrictions
- [ ] Two-factor authentication for sensitive items
- [ ] Temporary elevated privileges
- [ ] Delegation of access

---

## 📚 Related Documentation

- **Backend:** `backend/USER_ROLES_GUIDE.md`
- **Frontend:** `frontend/ADMIN_PORTAL_GUIDE.md`
- **Security:** `backend/middleware/auth.js`
- **Roles Setup:** `backend/scripts/seedRolesAndDepartments.js`

---

## ✅ Summary

The admin menu implements comprehensive role-based access control that:

✅ **Organizes admin functions** into logical sections
✅ **Shows only relevant items** based on user role
✅ **Hides empty sections** automatically
✅ **Provides visual feedback** with active states
✅ **Supports collapsible sections** for better organization
✅ **Displays user role** for clarity
✅ **Scales to future needs** with permission system
✅ **Follows security best practices** with server-side verification

The menu ensures users see only what they need, reducing clutter and improving the admin experience while maintaining security.