Docs/Roles & Permissions

Roles & Permissions

The application uses Spatie Laravel Permission to provide a production-ready RBAC system. You can create roles, assign permissions in a clean pill-style UI, and assign roles to users - all without touching code.

UI & design system
The admin design is based on the Vendventory admin interface. Branding colors are driven by the Primary and Secondary colors configured in Settings → Branding.

Dark mode
Dark mode is supported. Users can switch the overall theme from Settings → Branding, and the admin UI updates accordingly.

Installer default
The user created in Step 6 of the installer is automatically assigned the Admin role.

Admin role is protected
The Admin role has all permissions and cannot be edited or deleted. This prevents accidental lockouts and keeps deployments safe for buyers.

Modernization update: the Roles and Permission Glossary screens now use the same loader, shared inputs, confirmation flow, and toast feedback model used by the newer admin surfaces, so access-control work follows the same UI contract as the rest of the modernized application.

What changed in the current access-control surface

The roles index behaves like a live permission preview surface instead of a plain table.
Role create and update flows save asynchronously with confirmation and feedback.
The Permission Glossary is now an editable metadata layer with module, risk, title, description, sort order, and visibility controls.
Risk-aware glossary metadata helps administrators understand sensitive and critical permissions before assignment.

1) Module overview

Roles and permissions are stored using Spatie's standard tables (roles, permissions, role_has_permissions, and model_has_roles). Ovion extends the permissions table with extra metadata so buyers can understand each permission (what it does, which module it belongs to, and how risky it is) before assigning it to a role.

Internally, this module follows a clean Repository + Repository Interface structure (thin controllers, reusable business logic, easy extensions).

2) Permissions glossary

The permissions glossary is a buyer-friendly view of all permissions. Each permission includes a title, description, module, and risk level so the meaning is clear even for non-technical admins.

Screenshot

File: documentation/assets/media/roles/permissions-glossary.png

Extended permissions schema

Schema::table('permissions', function (Blueprint $table) {
    $table->string('title')->nullable()->after('name');          // Friendly name
    $table->text('description')->nullable()->after('title');     // What it does
    $table->string('module')->nullable()->after('description');  // e.g. Users, Settings
    $table->string('risk')->default('normal')->after('module');  // normal|sensitive|critical
    $table->unsignedInteger('sort_order')->default(0)->after('risk');
    $table->boolean('is_glossary_visible')->default(true)->after('sort_order');
});

If your code text looks "white", ensure your docs CSS styles pre/code colors. (Same fix applies across all docs pages.)

What each extra column means

title: A readable label shown in the UI (example: Manage Users).
description: Explains what the permission allows (example: Create, update, deactivate users).
module: Groups permissions by feature area (Users, Settings, Sales, etc.).
risk: Visual warning level: normal (safe), sensitive (private data / meaningful impact), critical (security, money, or core system behavior).
sort_order: Keeps permissions listed in a clean, predictable order.
is_glossary_visible: Controls whether the permission appears in the glossary UI (useful for internal/system-only entries).

3) Roles list

The Roles page lists all roles with quick visibility of what exists in the system. From here, admins can create new roles (for teams, branches, and job functions) and manage access in a structured way.

Screenshot

File: documentation/assets/media/roles/role-index.png

4) Create role (pill-style selection)

Creating a role is intentionally simple. Permissions are displayed as clickable "pills". Clicking a permission toggles it on/off, making it easy to build roles without scrolling through long checkbox lists.

Always read the permission risk and description before adding it to a role. Never assign critical permissions unless the role truly requires them.

Screenshot

Create role screen (pill-style permission selector)

File: documentation/assets/media/roles/role-create.png

What happens on save

The role is created in the roles table.
Selected permissions are stored in role_has_permissions.
The role becomes immediately available for assignment to users.

5) Assign roles to users

From the Assign Role screen, roles are attached to users. This updates Spatie's model_has_roles table. Once assigned, access rules apply immediately across the admin panel (menus, pages, actions, and protected routes).

How access is enforced

UI hides what a user should not see (menus and buttons).
Server-side authorization blocks restricted routes and actions (real security).
Security-sensitive actions can trigger admin notifications (in-app, and email where enabled).

Branding colors used in these screens follow the Primary & Secondary color configuration from Settings → Branding, and the overall UI is aligned with the Vendventory admin interface (Light & Dark mode supported).

6) Media placeholders

Access-control capture checklist

Image Placeholder

Roles index with permission preview panel

Capture the modern roles screen with live permission grouping, user counts, and glossary-aware role context visible at the same time.

Image Placeholder

Permission glossary with module and risk metadata

Capture the glossary showing title, description, module, and risk so the seeded permission metadata model is obvious.