Sindbad~EG File Manager

Current Path : /home/copmadinaarea/thecopmadinaarea.org/portal/docs/

Current File : /home/copmadinaarea/thecopmadinaarea.org/portal/docs/MODULE_MANAGEMENT_GUIDE.md

# 📋 Module Management System - Complete Guide

## 🎯 Overview

The Module Management system allows **superusers** to control which modules are visible and accessible to different admin levels (Assembly, District, and Area admins). This provides granular control over what features each user role can access.

---

## 🚀 Installation

### Step 1: Run the Installation Script

Visit: `http://localhost/copmadinaarea/install_module_management.php`

**Requirements:**
- Must be logged in as a superuser
- Database connection must be active

**What Gets Installed:**
1. ✅ `module_access_levels` table - Stores which access levels can see each module
2. ✅ `module_access_audit` table - Logs all access control changes
3. ✅ Updates to `module_management` table - Adds categories and system critical flags
4. ✅ Migration of existing modules to new system
5. ✅ Module Management module itself

### Step 2: Access the Module

After installation, you'll find **"Module Management"** in your sidebar under the **System** category.

---

## 🎨 Features

### 1. **Per-Level Module Control**
- Enable/disable modules for specific access levels
- Assembly, District, Area, and Superuser levels
- Toggle switches for each combination

### 2. **Module Categories**
Modules are organized into categories:
- **Navigation** - Home, Dashboard
- **Core Management** - Membership, Events, Programs, Ministries
- **Event Management** - Event Attendance, Forms, Reports
- **User Management** - Users, Member Accounts, Member Codes
- **System** - Settings, Email, Module Management
- **Reports** - Notifications, Audit Logs, Reports

### 3. **System Critical Modules**
Certain modules cannot be disabled:
- Dashboard
- Settings
- Notifications
- Users

These are marked with a 🔒 **Critical** badge.

### 4. **Access Level Hierarchy**

```
Superuser (👑)
↓ Can see everything
Area Admin (🗺️)
↓ Can see area-level modules
District Admin (📍)
↓ Can see district-level modules
Assembly Admin (⛪)
↓ Can see assembly-level modules
```

### 5. **Audit Trail**
All access changes are logged:
- Who made the change
- When it was made
- What module and access level
- Action (enabled/disabled)

---

## 📊 Using the System

### Dashboard Overview

When you open Module Management, you'll see:

**Statistics Cards:**
- Total Modules
- Active Modules
- Critical Modules
- Categories

**Access Level Guide:**
Visual guide showing what each access level represents.

### Managing Module Access

**For Each Module, You Can:**

1. **Toggle Access by Level**
- Click the toggle switch under each access level column
- Green = Enabled
- Gray = Disabled

2. **Activate/Deactivate Module**
- Use the power button in the Actions column
- Deactivated modules are hidden from ALL users

3. **View Module Details**
- Module name and description
- Icon representation
- Category
- System critical status

### Example Scenarios

**Scenario 1: Hide Member Accounts from Assembly Admins**
1. Find "Member Accounts" row
2. Click toggle under "Assembly" column to OFF
3. Assembly admins will no longer see this module

**Scenario 2: Enable Events Module for All Levels**
1. Find "Events" row
2. Ensure all 4 toggles (Assembly, District, Area, Superuser) are ON
3. All admin levels can now access Events

**Scenario 3: District-Only Module**
1. Find the module
2. Turn OFF: Assembly
3. Turn ON: District, Area, Superuser
4. Only District admins and above can access

---

## 🔧 Technical Details

### Database Structure

**module_access_levels Table:**
```sql
- id (Primary Key)
- module_id (Foreign Key to module_management)
- access_level (assembly, district, area, superuser)
- is_enabled (Boolean)
- enabled_by (User ID)
- enabled_at, updated_at (Timestamps)
```

**module_access_audit Table:**
```sql
- id (Primary Key)
- module_id (Foreign Key)
- access_level
- action (enabled, disabled)
- performed_by (User ID)
- reason (Text)
- performed_at (Timestamp)
```

### How Sidebar Filtering Works

**Old System (Hardcoded):**
```php
$menuStructure = [
['name' => 'Events', 'access' => 'viewer'],
// ... more modules
];
```

**New System (Database-Driven):**
```php
// Fetch modules from database
$moduleQuery = "
SELECT m.* FROM module_management m
LEFT JOIN module_access_levels mal ON m.id = mal.module_id
WHERE m.is_active = 1
AND mal.access_level = :user_access_level
AND mal.is_enabled = 1
";
```

**Benefits:**
- No code changes needed to update menu
- Real-time access control
- Centralized management
- Audit trail included

---

## ⚠️ Important Rules

### What You CAN Do:
✅ Enable/disable modules for Assembly, District, and Area admins
✅ Deactivate entire modules (non-critical ones)
✅ View access change history
✅ Organize modules by category

### What You CANNOT Do:
❌ Disable critical modules (Dashboard, Settings, etc.)
❌ Disable superuser access to any module
❌ Delete modules from the database (only deactivate)
❌ Change module categories (database-level change)

---

## 🧪 Testing Access Control

### Create Test Users
Use `create_test_users.php` to create:
- assembly_admin
- district_admin
- area_admin

**Test Process:**
1. As superuser, disable a module for Assembly level
2. Log out
3. Log in as assembly_admin
4. Verify module is NOT in sidebar
5. Log back in as superuser
6. Check audit log to see the change

---

## 📈 Best Practices

### 1. **Start Restrictive, Then Open Up**
- Begin with minimal access for Assembly admins
- Gradually enable modules as needed
- Monitor usage through audit logs

### 2. **Document Changes**
- Use the audit log to track what was changed
- Keep notes on why certain modules were restricted
- Review periodically

### 3. **Test Before Deploying**
- Always test with test user accounts
- Verify users can still do their essential tasks
- Don't restrict modules users actively need

### 4. **Module Categories**
Group related modules:
- Core operations should be widely accessible
- Administrative functions should be restricted
- System management should be superuser-only

### 5. **Communication**
- Inform users before restricting their access
- Explain why certain modules are restricted
- Provide alternative solutions if needed

---

## 🔍 Troubleshooting

### Module Not Showing in Sidebar

**Possible Causes:**
1. Module is deactivated globally
2. Access is disabled for that user's level
3. User needs to log out and back in
4. Database query error

**Solution:**
1. Check Module Management page
2. Verify module is Active
3. Check toggle for user's access level
4. Ask user to log out and log back in

### Can't Disable a Module

**Cause:** Module is marked as system critical

**Solution:** These modules cannot be disabled as they're essential for system operation.

### Changes Not Reflecting

**Cause:** User's session has cached menu

**Solution:** User must log out and log back in to see menu changes.

### Lost Access to Module Management

**Cause:** Only superusers can access this module

**Solution:** Log in with superuser account or contact system administrator.

---

## 📝 Adding New Modules

When you create a new module, add it to the database:

```sql
INSERT INTO module_management (
module_name,
module_description,
module_icon,
module_url,
display_order,
required_role,
is_active,
category
) VALUES (
'My New Module',
'Description of what it does',
'icon-name',
'modules/my-module/index.php',
50,
'assembly',
1,
'Core Management'
);
```

Then set access levels:

```sql
INSERT INTO module_access_levels (module_id, access_level, is_enabled)
SELECT id, 'assembly', 1 FROM module_management WHERE module_name = 'My New Module'
UNION ALL
SELECT id, 'district', 1 FROM module_management WHERE module_name = 'My New Module'
UNION ALL
SELECT id, 'area', 1 FROM module_management WHERE module_name = 'My New Module'
UNION ALL
SELECT id, 'superuser', 1 FROM module_management WHERE module_name = 'My New Module';
```

---

## 🎯 Quick Reference

**Toggle Module for Specific Level:**
1. Find module row
2. Click toggle under desired level column
3. Change is immediate

**Activate/Deactivate Entire Module:**
1. Find module row
2. Click power button in Actions column
3. Confirm the action

**View Access History:**
1. Scroll to bottom of page
2. "Recent Access Changes" section shows last 10 changes

**Access Module:**
- URL: `modules/module-management/index.php`
- Sidebar: System → Module Management
- Access: Superuser only

---

## 🔗 Related Systems

**Works With:**
- **Access Control System** (`config.php` helpers)
- **Sidebar Navigation** (`includes/sidebar.php`)
- **User Management** (access levels)
- **Audit Logs** (tracks changes)

**Integrates With:**
- Session management
- Database module system
- User roles and permissions

---

## 🆘 Support

**Common Questions:**

**Q: Can Assembly admins access Module Management?**
A: No, only superusers can manage module access.

**Q: Will disabling a module delete data?**
A: No, it only hides the module from the menu. All data remains intact.

**Q: How often should I review module access?**
A: Quarterly reviews are recommended, or when organizational structure changes.

**Q: Can I bulk-enable modules?**
A: Currently, you must toggle each module individually. Bulk actions may be added in future updates.

**Q: What happens to active users when I disable a module?**
A: Their current session continues, but module won't appear on next login.

---

## ✅ Summary

The Module Management system provides:
- ✅ Granular access control per admin level
- ✅ Real-time module visibility changes
- ✅ Complete audit trail
- ✅ Protected critical modules
- ✅ Easy-to-use interface
- ✅ Database-driven flexibility

**Perfect for organizations that need different admin levels to have different system capabilities!**

---

**Last Updated:** 2025-11-20
**Version:** 1.0
**Module:** Module Management
**Access Level:** Superuser Only

Sindbad File Manager Version 1.0, Coded By Sindbad EG ~ The Terrorists