# Admin Portal Guide

## Overview

The Madibeng Municipality Admin Portal is a comprehensive content management system designed for the Communications Unit staff. It provides role-based access control and allows users to manage website content based on their permissions.

## Access the Portal

**URL**: `http://localhost:3040/admin`

### Login Credentials

Use your registered email and password to log in. Contact your system administrator if you need an account.

## Features

### 📊 Dashboard (`/admin/dashboard`)
- Overview of system statistics
- Recent activity feed
- Quick action buttons
- Content status summary

### 📰 News Articles (`/admin/news-articles`)
- Create, edit, and delete news articles
- Publish/unpublish articles
- Mark articles as featured
- Search and filter by category and status
- View all articles in draft or published state

### 📅 Events (`/admin/events`)
- Manage municipality events
- Set event dates, locations, and details
- Publish upcoming events to the calendar
- Mark events as featured

### 📄 Pages (`/admin/pages`)
- Create and manage static pages
- Edit page content
- Control page publishing

### 📢 News Ticker (`/admin/news-ticker`)
- Manage news ticker items (scrolling news)
- Set item order and priority
- Quick updates for breaking news

### 🖼️ Media Library (`/admin/media`)
- Upload and manage images
- Organize media files
- Use media in articles, events, and pages

### 👥 User Management (`/admin/users`) *Manager/Admin Only*
- View all users
- Create new user accounts
- Edit user details and roles
- Activate/deactivate users
- Delete users
- Filter by role and status

### 🎭 Roles Management (`/admin/roles`) *Manager/Admin Only*
- View all roles and their permissions
- Create custom roles
- Assign permissions to roles
- Manage role hierarchy

### 🏢 Departments (`/admin/departments`) *Manager/Admin Only*
- Manage organizational departments
- Assign department managers
- View department statistics

### 📈 Analytics (`/admin/analytics`)
- View website statistics
- Content performance metrics
- User engagement data

### ⚙️ Settings (`/admin/settings`) *Manager/Admin Only*
- System configuration
- General settings
- Email/SMS configuration

## Role-Based Access

### 🔴 Communications Manager (Full Access)
- All permissions
- User management
- System settings
- Publishing and approval

### 🟡 Senior Communications Officer
- Publish and approve content
- View analytics
- No user management

### 🟢 Communications Officer
- Create and edit content
- Cannot publish
- Basic content management

### 🔵 Social Media Officer
- Social media content
- News tickers
- View analytics

### 🟣 Content Writer
- Create and edit articles
- Create pages
- Cannot publish

### 🟠 Graphic Designer
- Edit visual content
- Manage media library
- Cannot create new content items

### 🟤 Junior Communications Officer
- Basic content creation
- Limited editing
- Support role

### ⚪ Communications Intern
- Read-only access
- Learning role

## Quick Start

### 1. Login
1. Go to `http://localhost:3040/admin`
2. Enter your email and password
3. Click "Sign In"

### 2. Navigate
- Use the sidebar to access different sections
- Dashboard shows overview and quick actions
- Click on any menu item to access that section

### 3. Create Content

#### Creating a News Article:
1. Click "News Articles" in sidebar
2. Click "New Article" button
3. Fill in:
   - Title
   - Description
   - Content
   - Upload image
   - Select category
   - Mark as featured (optional)
4. Click "Save as Draft" or "Publish" (if you have permission)

#### Creating an Event:
1. Click "Events" in sidebar
2. Click "New Event" button
3. Fill in:
   - Title
   - Description
   - Start date/time
   - End date/time (optional)
   - Location
   - Upload image
4. Save or publish

### 4. Manage Users (Manager/Admin Only)
1. Click "Users" in sidebar
2. Click "Add User" to create new account
3. Fill in user details and select role
4. User receives verification email
5. Activate user account

## Content Workflow

### Standard Publishing Workflow

```
1. Writer creates draft article
   ↓
2. Officer reviews and edits
   ↓
3. Senior Officer approves
   ↓
4. Senior Officer or Manager publishes
```

### Urgent Update Workflow

```
1. Officer creates content
   ↓
2. Manager reviews and publishes immediately
```

## Tips & Best Practices

### ✅ DO:
- Save drafts regularly
- Use descriptive titles
- Add images to articles (recommended 1200x630px)
- Preview content before publishing
- Use categories consistently
- Add relevant tags to content

### ❌ DON'T:
- Publish without review (unless urgent)
- Use copyrighted images without permission
- Delete published content without backup
- Share login credentials
- Leave drafts unfinished for too long

## Common Tasks

### Publishing an Article
1. Open article in editor
2. Review content and images
3. Click "Publish" button
4. Confirm publication

### Unpublishing Content
1. Open published article
2. Click "Unpublish" button
3. Article returns to draft status

### Featuring an Article
1. Open article
2. Check "Featured" checkbox
3. Save changes
4. Featured articles appear in carousel

### Managing Users
1. Go to Users section
2. Search for user or browse list
3. Click edit icon to modify
4. Toggle active/inactive status
5. Save changes

## Troubleshooting

### Can't Login
- Verify email and password
- Check if account is activated
- Contact IT support if locked out

### Can't Publish Content
- Check your role permissions
- Only Senior Officers and Managers can publish
- Save as draft and request approval

### Image Not Uploading
- Check file size (max 5MB recommended)
- Use supported formats: JPG, PNG, WebP
- Check file name (no special characters)

### Permission Denied Errors
- Your role may not have required permission
- Contact Communications Manager
- Check if account is active

## Keyboard Shortcuts

- `Ctrl + S` - Save draft (in editors)
- `Ctrl + Enter` - Preview content
- `Esc` - Close modals

## Support

### Need Help?
- **IT Support**: it@madibeng.gov.za
- **Communications Manager**: For permission requests
- **Documentation**: `/admin/help`

### Report Issues
- Email: support@madibeng.gov.za
- Internal: Contact IT Department
- Urgent: Call IT Helpdesk

## Security

### Best Practices:
1. **Never share your password**
2. **Log out when finished**
3. **Use strong passwords** (min 8 characters, mixed case, numbers)
4. **Don't use public computers** for admin access
5. **Report suspicious activity** immediately

### Session Management:
- Sessions expire after 24 hours
- You'll be auto-logged out after inactivity
- You can manually logout anytime

## Updates & Changelog

### Version 1.0 (2026-01-31)
- Initial release
- Role-based access control
- Content management (Articles, Events, Pages)
- User management
- Dashboard and analytics

---

**Last Updated**: 2026-01-31  
**Version**: 1.0  
**Support**: communications@madibeng.gov.za