# 3. Permission Configuration

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

---

## 3. Permission Configuration

### 3.1 System-Wide Permission Catalog
**What it does:** Maintains the single source of truth for everything that can be granted: the full catalog of permissions — features (sections a role may open), actions within features (what a role may do), and data scopes (which records a role may see). Roles draw their permission sets from this catalog, so the catalog defines the upper bound of what any role can grant.

**Sub-features:**
- Permission catalog organized by module (Authentication, Courses, Content, Billing, etc.)
- Three permission types: feature access (open a section), action (perform an operation), data scope (see a record set)
- Catalog is system-managed: new permissions appear as platform capabilities are added; the Super Admin does not invent permissions
- Catalog browser: search and filter permissions by module, type, and name
- Permission detail view: what the permission grants, which roles currently hold it
- Read-only for the Super Admin (the catalog reflects platform capabilities, not user-defined entries)

**Super Administrator User Journey:**
1. While building a new custom role, Super Admin opens the permission catalog to see exactly what can be granted.
2. Browses by module: under "Billing" the catalog lists feature access (open Pricing Management), actions (create plan, process refund, configure gateway), and data scopes (all invoices, own-institute invoices).
3. Searches for "refund" and sees every permission containing that capability across modules, with the roles that currently hold each.
4. Selects the permissions the new role needs and adds them to the role editor.
5. Reviews the "held by" column to understand the blast radius: a permission held by many roles means granting it to the new role is low-risk; a rarely-held sensitive permission prompts a closer look.
6. Saves the role with the selected permissions.
7. Later, when a new platform capability ships (e.g., a new report type), its permission appears in the catalog automatically; Super Admin reviews new catalog entries periodically and decides which roles should receive them.
8. The catalog view is read-only — Super Admin cannot create, rename, or delete catalog entries; they reflect platform capabilities.

**Rules & Edge Cases:**
- The catalog is the upper bound: a role cannot grant a permission that is not in the catalog.
- Catalog entries are added by the platform as capabilities ship; they are not user-defined.
- Each permission's "held by" visibility supports informed granting (blast-radius awareness).
- Data-scope permissions are distinct from feature/action permissions; granting a feature without the data scope may still result in no visible records.
- The catalog is consistent across web and service surfaces — the same permission governs both.
- Catalog changes (new entries) are visible in the change history so role owners can review what became grantable.

### 3.2 Grant or Restrict Feature Access per Role
**What it does:** Controls which sections/features of the platform each role can open. The Super Administrator toggles feature access on or off per role in the role editor, shaping each role's navigation and reachable surface. Denial is enforced server-side, so a feature a role cannot access is unreachable even by direct navigation.

**Sub-features:**
- Feature-level toggles per role in the role editor (organized by module)
- Navigation shaping: a role's menu shows only the features it can access
- Server-side enforcement: direct navigation to an unpermitted feature is denied with a clear message
- Change preview: affected user count before saving
- Immediate propagation to holders
- Audit logging of feature-access changes

**Super Administrator User Journey:**
1. The support team should not see the Marketing & Communication module. Super Admin opens the Student Support Administrator role in the role editor.
2. Under the Marketing & Communication module, confirms the feature-access toggle is off (it is, by the role's default set).
3. For a new requirement — support admins should now see the Customer Support module's reporting section — Super Admin toggles on the specific feature (Support Reporting) without granting the rest of the module.
4. Reviews the change preview: "Affects 3 users — gains: open Support Reporting."
5. Saves; the 3 support admins see the new section in their navigation on their next request.
6. A support admin manually navigates to the Marketing module URL; the request is denied server-side with "You don't have permission to access this section," and the denial is logged.
7. Super Admin reviews the access-denied log to confirm enforcement and to spot any role repeatedly hitting denials (a misconfiguration signal).
8. The feature-access change is audit-logged with before/after state and the affected user count.

**Rules & Edge Cases:**
- Feature access is enforced at the service layer, not just the UI: hiding from the menu is a convenience, the denial is the control.
- A denied feature produces a clear message with an optional "request access" path.
- Granting a feature does not automatically grant its actions; actions are separate permissions (a role may open a section but only view, not edit).
- Change previews show the affected user count so grants are deliberate.
- All feature-access changes are audit-logged.
- The Super Administrator role has all feature access and is not subject to these toggles.

### 3.3 Scope Data Access per Role
**What it does:** Controls which records a role can see, not just which sections it can open. Data scoping binds a role's visibility to a record set — for example, a teacher sees only their assigned courses and students, a support agent sees only tickets in their queue, an institute's staff see only their institute's data. Scoping is applied on top of feature access: a role may open a section but see only its scoped records.

**Sub-features:**
- Scope types: all records, own records (assigned to the user), team/institute records, custom record-set rules
- Per-role scope configuration in the role editor (per data category: courses, students, tickets, invoices, etc.)
- Scope applied consistently across lists, detail views, search, and exports
- Multi-role scope resolution: where held roles scope differently, the policy-defined resolution applies (default: union of visible records)
- Scope preview: what a sample user of the role would see
- Audit logging of scope changes

**Super Administrator User Journey:**
1. A new institute joins with its own teachers and students. Super Admin reviews the Teacher/Content Creator role's data scope: "own records" for courses and students — each teacher sees only what is assigned to them.
2. Confirms the institute-level isolation: the role's scope for institute data is "own institute," so this institute's staff never see another institute's courses, students, or content.
3. For the institute's admin contact, Super Admin assigns a role scoped to "all records within own institute" so they can see the whole institute's data (but not other institutes').
4. Uses the scope preview to verify: a sample teacher sees only their 3 assigned courses; the institute admin sees all 40 courses in their institute.
5. Saves; the scoping applies immediately to lists, detail views, search, and exports for the role's holders.
6. A teacher attempts to open a course URL that is not assigned to them; the record is not visible to them (denied), and the attempt is logged.
7. During an access review, Super Admin re-runs the scope preview for key roles to confirm scoping still matches the operating model.
8. Scope changes are audit-logged with before/after scope definitions and the affected roles.

**Rules & Edge Cases:**
- Scoping applies to lists, detail views, search, and exports — a scoped-out record cannot be reached by any path.
- Two users with the same role can see different record sets (e.g., different teachers' courses); scoping is per-user within the role.
- Multi-role scope resolution follows the policy (default union); the resolution is documented and consistent.
- Granting feature access without the corresponding data scope can result in an empty view; the scope preview surfaces this.
- Institute-level isolation is a scope boundary: one institute's data is not visible to another institute's users.
- All scope changes are audit-logged.

### 3.4 Permission Change Preview and Propagation
**What it does:** Makes permission changes safe and predictable: before saving any change to a role's permissions (features, actions, or scopes), the Super Administrator sees a preview of exactly what will change and who is affected; on save, the change propagates immediately to all holders without requiring re-login.

**Sub-features:**
- Change preview: capabilities gained/lost and the affected user count
- Side-by-side before/after permission set
- Save confirmation with the preview summary
- Immediate propagation: holders' access updates on their next request
- No re-login required for holders
- Audit logging with before/after state and affected count

**Super Administrator User Journey:**
1. Super Admin is about to remove "Process refunds" from the Billing Administrator role (moving refund processing to a dedicated role). Opens the role editor and makes the change.
2. The preview appears: "Affects 3 users — loses: process refunds; keeps: view billing, manage plans, configure gateway."
3. Reviews the before/after side-by-side to confirm only the intended permission is removed.
4. Saves with confirmation. The change propagates immediately: the 3 billing admins can no longer initiate refunds on their next request.
5. One billing admin, mid-refund-screen, completes the current view but is denied when attempting to submit the refund; they see a clear "you no longer have permission" message.
6. Super Admin assigns the Refunds Processor role to the staff member who should handle refunds (see Role Assignment), restoring the capability where intended.
7. Reviews the audit entry: before/after sets, actor, affected count, timestamp.
8. Communicates the change to the affected team so the new refund path is understood.

**Rules & Edge Cases:**
- The preview is mandatory before save; there is no silent permission change.
- Propagation is immediate (next request); holders do not need to re-login.
- Removing a permission a user is actively using ends that capability on their next action; the current in-progress request completes.
- The before/after state is captured in the audit log for reconstruction.
- Bulk role edits (multiple permissions at once) produce a single preview covering all changes.
- The affected user count is always shown so the blast radius is explicit.