User / Role / Permissions

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

User is the packaged identity record that Pyle uses for staff and storefront accounts. Role and Permission are the access-control layers wrapped around that user record, backed by Spatie permission models and the shared action-policy system.

Parent hierarchy:

• Supporting Platform Capabilities
• Identity And Access Governance
• User / Role / Permissions

Primary implementation paths:

• packages/framework/src/Models/User.php
• packages/framework/src/Http/Controllers/Api/Admin/UsersController.php
• packages/framework/src/Http/Controllers/Api/Admin/Auth/RolesController.php
• packages/framework/src/Http/Controllers/Api/Admin/PermissionsController.php
• packages/admin/src/Livewire/Admin/Staff
• packages/admin/src/Livewire/Admin/Users/Row
• packages/storefront/src/Livewire/Storefront/MyAccount/Permissions

What Users Can Do With It

Direct capabilities

Operators can:

• list and search users through the admin API
• inspect staff through the packaged Employees page
• approve a user
• assign roles to a user from the admin user row dialogs
• assign permissions to a user from the admin user row dialogs
• review role and permission counts on the packaged staff and roles screens

Indirect capabilities

Other workflows use User, Role, and Permission to:

• gate access to admin pages and actions through policy checks
• decide whether a user is staff
• control storefront self-service permission access for customer users
• write activity-log entries when roles or permissions change

Things users cannot do directly

The shared package does not expose one single combined user, role, and permission workspace. The management flow is split across the staff page, row dialogs, and API endpoints.

Where It Is Managed

Channel	Role	Notes
Admin Employees page	Direct	The packaged staff page for user management
Admin users API	Direct	Search, show, and approval surface
Admin roles API	Direct	Role listing and user role assignment
Admin permissions API	Direct	Permission catalog surface
Admin user-row dialogs	Direct	Role and permission assignment dialogs
Storefront My Account permissions page	Indirect	Customer-facing page for authorized permission self-service

Sources:

• packages/admin/src/Livewire/Admin/Staff/Page.php
• packages/admin/src/Livewire/Admin/Staff/DataTable.php
• packages/admin/src/Livewire/Admin/Users/Row/AssignRolesDialog.php
• packages/admin/src/Livewire/Admin/Users/Row/AssignPermissionsDialog.php
• packages/storefront/src/Livewire/Storefront/MyAccount/Permissions/Page.php
• packages/framework/src/Http/Controllers/Api/Admin/UsersController.php
• packages/framework/src/Http/Controllers/Api/Admin/Auth/RolesController.php
• packages/framework/src/Http/Controllers/Api/Admin/PermissionsController.php

Channel-Level Field Coverage

Admin user API

The packaged user API exposes and filters:

• id
• name
• email
• locale
• customer_id
• roles

The same API can include:

• customer
• roles
• permissions

User model fields

The User model persists fields such as:

• first_name
• last_name
• nickname
• name
• email
• password
• locale
• customer_id
• approved
• blacklisted
• receive_all_order_notifications
• has_customers_restrictions
• has_locations_restrictions

Role and permission assignment

Role assignment works with role IDs.

Permission assignment works with permission names and is grouped by permission scope in the admin dialog.

Sources:

• packages/framework/src/Models/User.php
• packages/framework/src/Http/Controllers/Api/Admin/UsersController.php
• packages/admin/src/Livewire/Admin/Users/Row/AssignRolesDialog.php
• packages/admin/src/Livewire/Admin/Users/Row/AssignPermissionsDialog.php
• packages/framework/src/Actions/User/AssignRoles.php
• packages/framework/src/Actions/User/AssignPermissions.php
• packages/framework/src/Http/Controllers/Api/Admin/Auth/RolesController.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• searchable
• role-aware through HasRoles
• API-token aware through Sanctum
• activity-log aware

Important model behavior:

• getIsStaffAttribute() returns true when the user has the staff-login permission or the superadmin role
• scopeWhereIsStaff() and scopeWhereIsNotStaff() separate staff from storefront users
• scopeWhereApproved() and scopeWhereUnapproved() separate approved staff from pending staff

Source:

• packages/framework/src/Models/User.php

Relationships

User directly connects to:

• customer()
• roles
• permissions
• comments()
• ownedOrders()
• defaultLocations()
• assignedCustomers()
• assignedLocations()

Practical dependents:

• staff list and role-management screens
• customer-owned storefront permission access
• activity logs and comments on user-adjacent records

Rules And Downstream Effects

Policy-driven access

User access is policy-driven rather than hard-coded in the UI.

• ViewUserPolicy gates the staff page
• AssignRolesPolicy gates role assignment
• AssignPermissionsPolicy supports admin assignment and storefront assignment, but storefront access is only allowed for the current customer’s own users

Role assignment side effects

Assigning roles writes an activity-log entry describing added and removed roles.

Permission assignment side effects

Assigning permissions uses a cache lock, syncs the selected permissions, and writes an activity-log entry describing the changes.

Storefront access gate

The storefront My Account permissions page redirects unauthorized users back to the storefront home page.

Sources:

• packages/framework/src/Policies/Actions/User/ViewUserPolicy.php
• packages/framework/src/Policies/Actions/Role/AssignRolesPolicy.php
• packages/framework/src/Policies/Actions/Permission/AssignPermissionsPolicy.php
• packages/framework/src/Actions/User/AssignRoles.php
• packages/framework/src/Actions/User/AssignPermissions.php
• packages/storefront/src/Livewire/Storefront/MyAccount/Permissions/Page.php

Integrations And Automation

Search and notifications

Users are searchable through the shared search trait and can trigger downstream search updates when they change.

ERP bridge

The User model is ERP-bridge aware through the shared DTO contract.

Email flows

The model also drives verification and password-reset notifications.

Sources:

• packages/framework/src/Models/User.php
• packages/framework/src/Listeners/SyncSearchable.php
• packages/framework/src/Actions/Searchable/SyncModelToSearchable.php
• packages/framework/src/Actions/ErpBridge/User/ToDTO.php

Where It Appears To End Users

User, Role, and Permission are mostly operator concepts.

The packaged shared UI exposes them through:

• the Employees page for staff
• the user row dialogs for assigning roles and permissions
• the storefront My Account permissions page for authorized customer users

Current Documentation Takeaways

1. User is the record, and Role and Permission are the access layer around it.
2. Admin and storefront access are split by policy and context.
3. The shared package exposes real management screens, but not one central permissions studio.

Open Questions

• This pass did not inspect any host-app-specific staff or permission screens beyond the shared package surfaces.

Sources:

• packages/framework/src/Models/User.php
• packages/framework/src/Http/Controllers/Api/Admin/UsersController.php
• packages/framework/src/Http/Controllers/Api/Admin/Auth/RolesController.php
• packages/framework/src/Http/Controllers/Api/Admin/PermissionsController.php
• packages/admin/src/Livewire/Admin/Staff/Page.php
• packages/admin/src/Livewire/Admin/Staff/DataTable.php
• packages/admin/src/Livewire/Admin/Users/Row/AssignRolesDialog.php
• packages/admin/src/Livewire/Admin/Users/Row/AssignPermissionsDialog.php
• packages/storefront/src/Livewire/Storefront/MyAccount/Permissions/Page.php