Role-Based Access Control

📋 Overview

The Role-Based Access Control (RBAC) system provides a hierarchical permission structure with flexible user permission overrides. This allows for granular control over user actions while maintaining a clear role hierarchy.

Hierarchical Roles - Each role has a level indicating its position in the hierarchy
Permission Groups - Permissions are organized by modules for easier management
User Overrides - Individual users can be granted additional permissions outside their role
Role Inheritance - Higher-level roles inherently have lower-level role permissions

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              RBAC SYSTEM ARCHITECTURE                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐                │
│  │  app_users   │────▶│ user_roles   │────▶│    roles     │                │
│  │              │     │ (user_id FK) │     │ (role_id FK) │                │
│  └──────────────┘     └──────────────┘     └──────┬───────┘                │
│                                                      │                       │
│                                                      ▼                       │
│                                             ┌──────────────┐                │
│                                             │role_permissions│              │
│                                             │(many-to-many) │                │
│                                             └──────┬───────┘                │
│                                                    │                        │
│                                                    ▼                        │
│                                             ┌──────────────┐                │
│                                             │ permissions  │                │
│                                             │              │                │
│                                             │ - id         │                │
│                                             │ - name       │                │
│                                             │ - slug       │                │
│                                             │ - module     │                │
│                                             └──────────────┘                │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                    USER PERMISSION OVERRIDES                          │  │
│  │  ┌──────────────┐     ┌──────────────────┐                          │  │
│  │  │  app_users   │────▶│user_permissions  │                          │  │
│  │  └──────────────┘     │(individual perms)│                          │  │
│  │                       └──────────────────┘                          │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                              │
│  Hierarchy Levels:                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ Level 100 │ Super Admin  │ Full access to everything                │    │
│  │ Level 80  │ Admin         │ Manage users, content, settings           │    │
│  │ Level 60  │ Moderator     │ Content moderation, user warnings        │    │
│  │ Level 40  │ Editor        │ Create and edit content                  │    │
│  │ Level 20  │ User          │ Standard user permissions                │    │
│  │ Level 10  │ Guest         │ Read-only access                         │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

📊 Table Reference

roles

Defines available roles in the system with hierarchy levels.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`name`	VARCHAR(50)	UNIQUE	Role display name (Super Admin)
`slug`	VARCHAR(50)	UNIQUE	URL-friendly identifier (super-admin)
`description`	TEXT	NULLABLE	Role description
`level`	TINYINT	Default: 10	Hierarchy level (10-100)
`created_at`	TIMESTAMP	Auto	Creation timestamp
`updated_at`	TIMESTAMP	Auto	Last update timestamp

permissions

Defines individual permissions grouped by modules.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`name`	VARCHAR(100)	UNIQUE	Permission name (Create User)
`slug`	VARCHAR(100)	UNIQUE	Identifier (users.create)
`description`	TEXT	NULLABLE	Permission description
`module`	VARCHAR(50)	NOT NULL	Module grouping (users, content, settings)
`created_at`	TIMESTAMP	Auto	Creation timestamp
`updated_at`	TIMESTAMP	Auto	Last update timestamp

role_permissions

Junction table linking roles to permissions (many-to-many).

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`role_id`	BIGINT	FK	References roles.id
`permission_id`	BIGINT	FK	References permissions.id
`created_at`	TIMESTAMP	Auto	Creation timestamp

user_roles

Assigns roles to users. A user can have multiple roles.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`user_id`	VARCHAR(32)	FK	References app_users.user_id
`role_id`	BIGINT	FK	References roles.id
`assigned_by`	VARCHAR(32)	NULLABLE	User ID who assigned this role
`expires_at`	TIMESTAMP	NULLABLE	Role expiration (temporary access)
`created_at`	TIMESTAMP	Auto	Assignment timestamp

user_permissions

Grants individual permissions to users outside their role assignments.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`user_id`	VARCHAR(32)	FK, UNIQUE	References app_users.user_id
`permission_id`	BIGINT	FK, UNIQUE	References permissions.id
`granted_by`	VARCHAR(32)	NULLABLE	User ID who granted this permission
`expires_at`	TIMESTAMP	NULLABLE	Permission expiration
`created_at`	TIMESTAMP	Auto	Grant timestamp

🔑 Default Roles

Super Admin (Level 100)

Full system access including user management, role assignments, and system configuration.

Admin (Level 80)

Administrative access for managing users, content, and settings without role assignment.

Moderator (Level 60)

Content moderation, user warnings, and community management permissions.

Editor (Level 40)

Create and edit content with publishing permissions.

User (Level 20)

Standard user permissions for creating personal content and basic interactions.

Guest (Level 10)

Read-only access for unauthenticated or limited users.

💻 Usage Examples

// Assign a role to a user
$user = AppUser::find('ABC123');
$user->roles()->attach(2, [
    'assigned_by' => auth()->id(),
    'expires_at' => now()->addMonths(6),
]);

// Grant individual permission to user
$user->permissions()->attach(15, [
    'granted_by' => auth()->id(),
]);

// Check if user has permission (via role or individual)
$hasPermission = $user->roles()
    ->whereHas('permissions', function($q) use ($permissionSlug) {
        $q->where('slug', $permissionSlug);
    })->exists() || $user->permissions()->where('slug', $permissionSlug)->exists();

// Get all permissions for a user (roles + individual)
$allPermissions = $user->roles()
    ->with('permissions')
    ->get()
    ->pluck('permissions')
    ->flatten()
    ->merge($user->permissions)
    ->unique('id');

// Check role hierarchy (higher level includes lower level permissions)
$userHighestLevel = $user->roles->max('level');
$canManage = $userHighestLevel > $targetUser->roles->max('level');