Roles & Permissions
Role-based access control (RBAC) system with per-user permission overrides and security-level enforcement.
Overview
The Roles & Permissions module controls what each administrator can see and do within the platform. It implements a two-layer access control model:
- Roles define a baseline set of permissions shared by all users assigned to that role.
- Per-user overrides allow granting extra permissions (exceptions) or revoking specific permissions for individual administrators, without modifying the role itself.
A security level mechanism (1–3) restricts which users can assign or remove sensitive permissions, preventing privilege escalation.
Key Concepts
| Concept | Description |
|---|---|
| Role | Named group of permissions with a security level (e.g. CSR, KAE, Admin) |
| Permission | Atomic right to view a section, perform an action, or see a menu item |
| Security level | Numeric tier (1, 2, 3) that gates who can grant/revoke a permission |
| Inherited | Permission that comes from the user's assigned role |
| Exception | Permission granted to a specific user outside the role's defaults |
| Revoked | Permission denied for a specific user even though the role includes it |
Data Flow
Permission Resolution
When the frontend loads, it fetches the administrator's effective permissions and uses them to build the sidebar menu and enable/disable UI actions.
Permission Assignment
When an admin assigns permissions to another user, the security level is validated server-side.
Database
Tables
| Table | Purpose |
|---|---|
roles | Role definitions (name, security level, timestamps) |
permissions | Permission definitions (name, module grouping, security level) |
role_permissions | Many-to-many relationship between roles and permissions |
admin_permissions | Per-administrator permission overrides (exceptions and revocations) |
administrators | Administrator records linking a user to a role, department, and office |
Entity Relationships
Key Fields
roles.security_level: Determines the maximum permission security level that users with this role can assign. Value range: 1–3.permissions.security_level: The minimum role security level required to assign or revoke this permission.permissions.parent_id: Groups permissions into modules (parent = module header, children = individual permissions).admin_permissions.action:1= granted (exception),-1= revoked.admin_permissions.is_inherited:trueif the permission comes from the role,falseif it's a per-user override.
Key Decisions
| Decision | Reasoning | Alternatives Considered |
|---|---|---|
| Two-layer model (role + user overrides) | Allows bulk permission management via roles while still handling individual exceptions without creating a new role per edge case | Pure role-based (no overrides), attribute-based access control (ABAC) |
| Numeric security levels (1–3) | Simple to implement and understand; prevents lower-level admins from escalating privileges | Fine-grained permission-on-permission system, hierarchical role inheritance |
| Server-side level validation | Frontend disables switches as UX hint, but the API enforces the rule to prevent bypass | Frontend-only enforcement |
| Permissions as flat list with parent grouping | Keeps the database schema simple while allowing module-based grouping in the UI | Nested permission trees, tag-based grouping |
Dependencies
- Internal: Authentication module (login, token validation), Sidebar/menu builder (reads permissions to render navigation)
- External: None (self-contained RBAC system)
Related Documentation
- User Guide: Roles & Permissions Guide — End-user instructions
- API Endpoints: Roles & Permissions API — Endpoint reference for this module