# 1. Role Definition

User Type: **Super Administrator**
Source: *Mi Digital Academy - Education CRM Features Document*

---

## 1. Role Definition

### 1.1 Create Custom Roles
**What it does:** Lets the Super Administrator define a new role with a custom name, description, and permission set, extending beyond the predefined sub-administrator roles. A new role starts with no permissions (deny-by-default) and the Super Administrator builds its capabilities from the permission catalog. Roles are the unit of access control: users gain access through the roles they hold, not through individual grants.

**Sub-features:**
- Role creation form: name (unique), description, optional category/tag
- Starting permission set: empty by default, or copy from an existing role as a starting point
- Permission assignment from the catalog during creation (features, actions, data scopes)
- Uniqueness validation on role name
- Role status: active/inactive (inactive roles cannot be assigned; existing holders keep access until reassigned)
- Audit logging of role creation with the initial permission set

**Super Administrator User Journey:**
1. The operations team needs a new role, "Course Operations" — staff who manage course scheduling and enrollment but cannot touch billing or content approval. Super Admin opens Role & Permission Management → Roles and selects "Create role".
2. Enters the name "Course Operations" and a description. The system validates the name is unique.
3. Chooses "Copy permissions from" and selects the Teacher/Content Creator role as a starting point, then removes the content-creation permissions that Course Operations staff should not have.
4. Adds the required permissions from the catalog: view courses, manage scheduling, view enrollment lists, export enrollment reports.
5. Reviews the final permission set in the role editor, organized by module, and confirms no billing or approval permissions are included.
6. Saves; the role is created as active and appears in the role list and in the role-assignment picker.
7. The creation is audit-logged with the initial permission set.
8. Super Admin assigns the role to the first Course Operations staff member (see Role Assignment) and verifies their access matches the intended scope.

**Rules & Edge Cases:**
- Role names are unique across the platform; duplicates are rejected at creation.
- A new role has no permissions until granted — deny-by-default.
- Copying from an existing role copies the current permission set; later changes to the source role do not propagate to the copy.
- Inactive roles cannot be assigned to new users; existing holders keep access until Super Admin reassigns them.
- Role creation is audit-logged with the actor, timestamp, and initial permission set.
- The Super Administrator role itself cannot be created, edited, or deleted through this flow (it is a fixed, full-access role).

### 1.2 Edit Roles
**What it does:** Lets the Super Administrator modify an existing role's details (name, description, status) and its permission set over time as the organization's needs change. Permission edits propagate immediately to all users holding the role, with a preview of the impact before saving.

**Sub-features:**
- Edit role name and description (renaming preserves the role's identity; holders are unaffected)
- Toggle role status active/inactive
- Add or remove permissions from the role's set
- Change preview: affected user count and capabilities gained/lost
- Immediate propagation to all holders on their next request
- Audit logging of every edit with before/after permission sets

**Super Administrator User Journey:**
1. The content review process changes: Content Reviewers now also need to approve resource library items. Super Admin opens Role & Permission Management → Roles and selects the Content Reviewer role.
2. Opens the role editor and reviews the current permission set.
3. Adds "Approve resource library items" from the catalog.
4. Reviews the change preview: "Affects 4 users — gains: approve resource library items."
5. Saves; the change propagates immediately. The 4 reviewers see the new approve action in their review queue on their next request.
6. Super Admin verifies with one reviewer that the new action is visible and functional.
7. The edit is audit-logged with the before/after permission sets, the actor, and the affected user count.
8. Later, when the process reverts, Super Admin removes the permission with the same preview-and-save flow, and the audit trail shows both changes.

**Rules & Edge Cases:**
- Renaming a role does not break assignments; the role's identity is stable, only the label changes.
- Removing a permission takes effect on the holder's next request; in-progress screens complete the current action but cannot initiate new actions with the removed permission.
- The preview always shows the affected user count so the change is deliberate.
- Every edit is audit-logged with before/after state.
- Editing a role does not require holders to re-login; propagation is prompt.
- The Super Administrator role cannot be edited through this flow.

### 1.3 Delete and Archive Roles
**What it does:** Controls the end of a role's life. A role with no users can be deleted outright; a role with holders must first be archived (or its holders reassigned), preventing accidental loss of access or orphaned assignments. Archiving blocks new assignments while preserving the role's history for audit.

**Sub-features:**
- Delete: available only for roles with zero holders; removes the role and its permission set
- Archive: available for roles with holders; blocks new assignments, retains the role and its audit history
- Reassignment assistance: list of current holders with a path to assign replacement roles before deletion
- Confirmation with impact summary (holders, permissions, recent usage)
- Audit logging of deletion/archival with the actor and reason

**Super Administrator User Journey:**
1. After a reorganization, the "Legacy Billing" role is no longer needed. Super Admin opens the role list and checks its holders: 2 users.
2. Selects "Archive" (delete is unavailable while holders exist). A confirmation shows: "2 users currently hold this role. Archiving will prevent new assignments; existing holders keep access until reassigned."
3. Confirms the archival with the reason "Role retired after billing reorganization."
4. The role now appears as archived in the role list and is excluded from the role-assignment picker.
5. Super Admin reassigns the 2 holders to the current Billing Administrator role (see Role Assignment), verifying each retains the required billing capabilities.
6. With zero holders, Super Admin deletes the archived role; a final confirmation shows the role's permission set and its last-usage date.
7. The deletion is audit-logged; the role's history (creation, edits, holders over time) remains in the audit trail.
8. Super Admin reviews the role list to confirm the active role set matches the current organization model.

**Rules & Edge Cases:**
- Deletion is blocked while any user holds the role; the UI shows the holder count and guides reassignment.
- Archived roles cannot be assigned to new users but remain visible for audit and can be reactivated.
- Archival does not change the access of existing holders until they are reassigned.
- Deletion is irreversible; the role's permission set is removed, but its audit history is retained.
- Every deletion/archival requires a recorded reason and is audit-logged.
- The predefined sub-administrator roles and the Super Administrator role cannot be deleted (they can be archived only where policy allows).

### 1.4 Predefined Sub-Administrator Roles
**What it does:** Provides a set of ready-to-use sub-administrator roles aligned with the platform's operating model — Billing Administrator, Teacher/Content Creator, Content Reviewer, and Student Support Administrator — each with a sensible default permission set. These reduce setup time for common staff types and provide a consistent baseline that custom roles can copy from.

**Sub-features:**
- Billing Administrator: manages plans, pricing, discounts, payments, refunds, and billing reports; no access to content or curriculum
- Teacher/Content Creator: creates and manages assigned courses and content; no access to billing, pricing, or platform-wide settings
- Content Reviewer: reviews and approves/rejects content submissions; read access to content, no creation or billing access
- Student Support Administrator: manages student accounts, support tickets, and student data within scope; no access to billing configuration or content approval
- Default permission sets are editable (predefined roles are starting points, not fixed)
- Protection: predefined roles cannot be deleted; they can be archived or edited
- Usage visibility: holder count and last-activity per predefined role

**Super Administrator User Journey:**
1. A new institute onboards 3 teachers and 1 billing contact. Super Admin opens the role list and reviews the 4 predefined sub-administrator roles and their default permission sets.
2. Confirms the Teacher/Content Creator default set matches the institute's needs (create courses, upload content, view their own analytics) and assigns it to the 3 teachers.
3. Assigns Billing Administrator to the billing contact and reviews that role's set: plans, pricing, discounts, payments, refunds, billing reports — and confirms no content or curriculum access.
4. The institute later asks that its teachers also view the resource library. Super Admin edits the Teacher/Content Creator role (or creates an institute-specific copy) to add resource library read access, previews the impact (all holders of that role), and saves.
5. Reviews the usage visibility: holder counts and last-activity per role, confirming the roles are being used as intended.
6. When a staff type no longer fits a predefined role, Super Admin copies the closest predefined role into a custom role and tailors it, leaving the predefined baseline intact for future staff.
7. Super Admin reviews the audit trail for role assignments and edits to confirm all changes are recorded.

**Rules & Edge Cases:**
- Predefined roles are editable but not deletable; the platform's operating model assumes their existence.
- Editing a predefined role affects all its holders across all institutes; where an institute needs a variation, a custom copy is the recommended path.
- The default permission sets follow separation of duties: no single predefined role combines content approval with billing, or billing configuration with refund approval.
- Holder count and last-activity are visible per role to support staffing and access reviews.
- All changes to predefined roles are audit-logged like any other role edit.
- The Super Administrator role is separate from these sub-administrator roles and is not part of this predefined set.