Management Guide

This guide covers the management subsystems: Role-Based Access Control (RBAC), user management, intern management, organizational structure, and lookup configuration.

Database-Driven All roles, permissions, and assignments are stored in the database. There are no hardcoded roles in the application code. Changes to permissions take effect immediately without code deployment.

Role-Based Access Control (RBAC)

Core Concepts

Concept	Description
Role	A named set of permissions (e.g., "admin", "coordinator", "supervisor", "intern", "center_head", "employee")
Permission	A granular action that can be performed (e.g., `users.view`, `tasks.create`, `reports.export_pdf`)
Role-Permission Assignment	Which permissions a role has. Managed via the Role Matrix.
User-Role Assignment	Which roles a user holds. A user can have multiple roles (except Intern).

Default Roles

Role	Description	Exclusive?
admin	Full system access. Can manage all settings, users, and data.	No
coordinator	Manages internship programs, sessions, and reports.	No
supervisor	Guides assigned interns, manages tasks, approves logs.	No
center_head	Oversees a research center and its interns.	No
employee	PIDE staff member with basic portal access.	No
intern	Internship participant. Cannot hold other roles simultaneously.	Yes

Permission Naming Convention

Permissions follow the format: {module}.{action}

users.view — View user list
users.create — Create new users
users.update — Edit user details
users.delete — Deactivate users
tasks.view — View tasks
tasks.create — Create tasks
daily_logs.approve — Approve daily logs
reports.export_pdf — Export reports as PDF

Parent Permissions Parent permissions (e.g., users.manage) auto-grant all child permissions when assigned. This simplifies role configuration.

Role Management

Navigate to Roles to manage system roles. Requires rbac.manage permission.

Available Actions

Action	Description
Create Role	Define a new role with a name, slug, and description
Edit Role	Modify role name, description, or status
Clone Role	Duplicate an existing role with all its permissions
Archive Role	Disable a role. Archived roles cannot be assigned to new users.

Permission Management

Navigate to Permissions to view and manage all system permissions.

View — See all permissions grouped by module
Create — Add a new permission (slug, name, module)
Delete — Remove a permission (with confirmation)

Caution Deleting a permission removes it from all roles that have it assigned. This cannot be undone without recreating the permission and re-assigning it.

Role Matrix

The Role Matrix is a grid that shows which permissions each role has. It provides a visual overview of the entire permission structure.

Rows represent permissions
Columns represent roles
Checkboxes indicate whether a role has a permission
Changes are saved immediately

How to Use the Role Matrix

1

Navigate to Roles → Role Matrix Open the matrix view from the sidebar.

2

Toggle Permissions Check or uncheck boxes to grant or revoke permissions for each role.

3

Save Changes Click "Save" to apply all changes. The new permissions take effect immediately for all users.

User Management

Comprehensive user management with import, export, and bulk actions.

User List Features

Search — Full-text search across name and email
Filter by Department — Narrow results by department
Filter by Role — Show only users with a specific role
Filter by Status — Active, inactive, or all
Team View — See users in a team/org-chart layout
Popup Preview — Quick-view user details without leaving the list

User Actions

Create — Manual user creation with role assignment
Edit — Update user details, department, and roles
Import — Bulk import from CSV file
Export — Download user list as CSV
Deactivate — Disable a user account
Welcome Email — Send or resend welcome email with password-set link
Password Reset — Send password reset link
Bulk Welcome/Reset — Send emails to all filtered users at once

Business Rules

Email must be unique across all users
Users can hold multiple roles except Intern (exclusive)
Adding Intern role to an account with other roles will fail validation
New users are created as inactive until they activate via email
Deactivated users cannot log in but their data is preserved
Supervisor hierarchy is validated to prevent circular relationships (e.g., A supervises B who supervises A)

Intern Management

Dedicated management interface for intern lifecycle.

Intern Status Pipeline

Status	Description	Next Step
Registered	Intern has registered, email not yet verified	Email verification
Profile Incomplete	Email verified, wizard not finished	Complete profile wizard
Profile Complete	All wizard steps done	Center allocation
Allocated	Assigned to a research center	Supervisor assignment
In Progress	Supervisor assigned, internship active	Complete internship
Completed	Internship finished	Certificate generation

Organizational Structure

Research Centers & Sections

14 default centers/sections are seeded during initial setup
Centers can contain multiple sections
Interns are allocated to a specific center/section
Centers can be created, edited, and deleted

Departments

19 default departments are seeded during initial setup
Users (employees) are assigned to a department
Departments are used for filtering in reports and user management

Universities

All Pakistani universities are seeded in the system
Interns select their university during registration
Universities can be managed (add, edit, delete) by administrators

Lookups

Lookup tables store reference data used across the portal
5 seeded categories with 24 values (e.g., degree types, gender options)
Lookups can be managed: add categories, add/edit/delete values
Used in dropdowns throughout the portal