User Management & Access ControlCore Module

Roles & RBAC

1. Overview & Purpose

What are Roles & RBAC?

Roles & RBAC defines functional authorization archetypes across the organization. It establishes organizational hierarchy levels, configures branch context switching modes (STRICT vs FULL), and groups fine-grained permissions for staff assignment.

Menu Location:User Management > Roles

2. When to Use Roles Management

Organizational Hierarchy & Role Levels (Rank 1 to 5)

The enterprise establishes formal staff tiers (Rank 1 Cashier, Rank 2 Supervisor, Rank 3 Store Manager, Rank 4 Finance Director, Rank 5 Executive).

Recommended Action:Create distinct role records and configure the level attribute; higher-rank roles hold authority to sign off on approval gates and override lower-tier blocks.

Branch Context Mode Partitioning (STRICT vs FULL)

Frontline store cashiers must be locked strictly to their store outlet, whereas regional operations directors require global visibility across all 12 branches.

Recommended Action:Configure contextMode = STRICT for store staff (hiding multi-branch selector), and contextMode = FULL (isFullContext = true) for corporate leadership.

System Role Immutability & Kernel Protection

A junior IT administrator attempts to delete or rename the root Super Admin role to customize the navigation interface.

Recommended Action:Roles flagged with isSystem = true or code = super are locked by platform kernel safeguards, permanently preventing deletion or lockout of root access.

Departmental Job Specialization (Warehouse vs Purchasing vs Sales)

Preventing warehouse receiving staff from viewing sales margins, and restricting sales reps from approving purchase order supplier costs.

Recommended Action:Create tailored role profiles (e.g. warehouse_clerk, sales_representative) and map each role to strictly relevant modules in Matrix Permissions.

Read-Only External Auditor & Tax Consultant Role

External financial auditors require access to examine transaction histories and general ledgers without holding any creation or modification authority.

Recommended Action:Establish an "Auditor" role with contextMode = FULL and grant read-only (View) permissions across modules while unchecking Create, Update, and Delete.

3. Data Dictionary & Fields

Schema structure for the roles authorization table:

Field / Column	Input Type	Requirement	Description & Operational Guide
code	STRING(50)	Required	Unique machine-readable role identifier (e.g. super, admin, cashier, finance).
name	STRING(50)	Required	Human-readable title displayed on user forms and role badges.
description	STRING(255)	Optional	Operational summary of responsibilities assigned to this role.
level	INTEGER	Optional	Hierarchical rank used to govern supervisory delegation and approval boundaries.
contextMode	STRING(20)	Required	Context scope mode: STRICT locks to user scopes, FULL allows viewing all branches.
isFullContext	BOOLEAN	Required	Computed boolean derived from contextMode (true when mode is FULL).
isSystem	BOOLEAN	Required	Protection flag for built-in system roles (super, admin) preventing deletion.

4. Interface Preview

Role management screen showing system role badges, context modes (STRICT vs FULL), level hierarchies, and edit actions.

inventories-web

Menu Location:Route: /admin/user-management/roles

Screen Preview: Role Management Console Interface

Visual interface illustration and control layout for menu Route: /admin/user-management/roles

1Add Role Form2Context Mode Badges3System Lock Indicator4Level Hierarchy Editor

Role setup grid showing custom and system roles, context switching parameters, hierarchical levels, and deletion safety guards.

5. Creating a Role

Navigate to Roles Console

Select User Management > Roles from the primary navigation.

Launch Role Creation Dialogue

Click Add Role in the top toolbar to open the specification modal.

Enter Code & Role Name

Provide a unique lowercase code (e.g. store_manager) and display name.

Select Context Mode

Choose STRICT for single-branch store personnel or FULL for HQ executives.

STRICT roles must always have branches assigned in User Scopes.

Save Role Profile

Click Submit to persist the role, then proceed to Matrix Permissions to grant access.

6. Context Mode Configuration

Locate Role

Find role row by code or name using the table search bar.

Modify Configuration

Click Edit to adjust display name, description, level rank, or context mode.

Save Updates

Confirm updates. Changes take effect on next token or context refresh.

7. Role Deletion & System Locks

System Role Immutability

Core system roles such as Super Admin (code: super) and Administrator are locked permanently by the platform kernel. They cannot be renamed or deleted under any circumstance.

System Role Protection

Roles flagged with isSystem = true or code = super cannot be deleted.

Reassign all active users to an alternative role before deleting a custom role.

8. Cross-Module Impact

Target Subsystem	Relational & Transactional Effect
Matrix Permissions	Every role forms a column in the permission matrix granting or denying specific endpoints.
User Accounts	Users inherit their operational capabilities and interface visibility from their role.
Branch Context Guard	Dictates whether the user interface displays the branch switcher dropdown or locks to one branch.

Operational Best Practices

Create granular roles aligned to actual job titles rather than granting generic admin status.
Keep contextMode STRICT for cashiers and warehouse attendants to avoid cross-branch stock leakage.