Skip to Content
Tenant BackofficeSettingsRoles & Permissions

Roles & Permissions

  • Code: SET-ROL
  • Module: Settings
  • Type: Master Data

1. Overview

A Role is a set of permissions granted to users. The admin creates roles such as “Store Manager” or “Purchasing”, then picks their permissions from a catalog organized in levels: Module → Feature → Action. A user can have more than one role, and their permissions are the union of all their roles. Every permission also has a scope: it applies to all stores, or is limited to the stores the user is assigned to.

Expected outcome: the tenant can control who may do what without code changes, with granularity down to the action level.

2. Problem

Without role-based grouping of permissions, controlling who may do what has to be done one person at a time, which is hard to scale. As a result:

  • Staff duties differ; giving everyone all access is risky.
  • Permissions that are only distinguished per module are too coarse; for example, staff may create a PO but not submit it.
  • Managing permissions per person does not scale; they need to be grouped per role.

3. Goals & Non-goals

3.1 Goals

  • Access can be restricted down to the action level, for example allowed to create an order but not to submit it.
  • Authority is defined once per role, then reused for everyone with the same responsibilities.
  • The authority contained in a role can be checked before it is given to someone else.
  • Authority changes can be made by the tenant themselves, without involving the technical team.

3.2 Non-goals

  • Creating new permission types from within the app; the catalog is predefined.
  • Granting permissions directly to users outside of roles.
  • Restricting to specific stores at the role level; the store scope follows the user’s assignments.

4. Business Rules

Business rules are the set of provisions and constraints that apply to Roles throughout the application, on every screen and action that involves it, whoever performs it. These rules are the single source of truth: if another part of this PRD appears to differ, the rules here prevail.

  • BR-01 Every role must have a name and at least one permission.
  • BR-02 Every permission applies to one action on one feature, with a scope of all data or limited to the stores the user is assigned to.
  • BR-03 The permissions that apply to a user are the union of all their roles.
  • BR-04 The permission catalog is predefined and cannot be extended or changed from this page.
  • BR-05 Users without a permission cannot open the related page or run the related action, whichever path triggers it.
  • BR-06 The navigation menu only shows items for which the user has the permission.

5. Flow

5.1 Main Flowchart

  1. Role Name — The admin names the role according to its responsibilities, for example Store Manager or Purchasing.
  2. Choose Module — Permissions are browsed per module, and all actions in one module can be selected at once.
  3. Choose Actions — Within a module, actions are selected per feature or one by one, according to the authority to be granted.
  4. Validation — A role must have a name and at least one permission before it can be saved.
  5. Role Saved — The role is ready to be given to users.
  6. Assignment to Users — The role is selected for users from the Users menu, and its permissions take effect immediately.

6. Document Structure

6.1 General

FieldTypeRequiredDefaultRules
Role NameTextYes—— (BR-01)
PermissionsRef. Action, multipleYes, at least 1—Selected from the permission catalog (BR-01)

6.2 Permission

LevelContentProvision
ModuleModule name and its list of featuresFor example Purchase, Settings
FeatureFeature name and its list of actionsFor example Purchase Order
ActionAction nameWhat is stored on the role, displayed and searchable

7. UI Structure

This section defines how Roles are displayed and operated: the list columns and form controls along with their option sources. This section only governs display and interaction; content and value rules still follow Document Structure.

7.1 Datatable

ColumnSortableSample ValueComponent
Role Name—Store ManagerText
Permissions—24 permissionsText
Actions—View · Edit · DeleteAction Menu

7.2 Form & Details

Create — A Role Name form, followed by a hierarchical permission picker: a tab per Module, a card per Feature inside it, and a chip per Action. Action: Save.

Edit — The same layout as Create, filled with the permissions already selected. Action: Save, only enabled when there are changes.

Detail — The same layout, but checkboxes are hidden and only modules and features with selected actions are shown. Actions: Edit Data, Delete.

FieldControlOptions SourceBehavior
Role NameText Input——
PermissionsTab per Module, card per Feature, chip per ActionPermission catalog (Module → Feature → Action)The Module checkbox selects all actions in the module; the Feature checkbox selects all actions in the feature; each Feature card has an action search box

8. User Stories

US-01 - Create a role

As an owner, I want to create a role with specific permissions, so that it can be given to users.

IDAcceptance criteria
AC-01.1The form contains the role name and a hierarchical Module → Feature → Action permission picker.
AC-01.2The role name is required; at least one permission must be selected.
AC-01.3The module checkbox selects/clears all actions in the module; the feature checkbox selects/clears all actions in the feature.
AC-01.4Each feature shows the number of actions and an action search box; all features are expanded on first load.
AC-01.5On success, a success toast appears and the user is redirected to the role list.
AC-01.6Duplicate role name — Needs confirmation: whether it is rejected as a duplicate; the error appears on the field.
AC-01.7The permission catalog is empty — “Data not found” appears in the permission picker.

US-02 - View role detail

As an admin, I want to see a role’s permissions, so that I am confident before assigning it.

IDAcceptance criteria
AC-02.1The detail only shows modules and features that have at least one selected action.
AC-02.2Checkboxes are not shown and the module tabs cannot change the selection.

US-03 - Edit a role

As an owner, I want to change a role’s name or permissions, so that it matches the latest needs.

IDAcceptance criteria
AC-03.1The Edit Data button only appears for users with the update permission.
AC-03.2Validation is the same as on creation; the save button is only enabled when there are changes.
AC-03.3Permission changes apply to all users who have that role.
AC-03.4Removing or reducing permissions of a role held by the logged-in admin — not prevented while filling in; it must be rejected on save so the tenant does not lose all Settings access.
AC-03.5A role’s permissions are changed while its users are logged in — they take effect at the next permission check (page render or API call).
AC-03.6Role changes are not recorded — roles do not have an activity log in the UI yet.

US-04 - Role list

As an owner, I want to see all roles, so that they are easy to manage.

IDAcceptance criteria
AC-04.1Columns: role name and number of permissions.
AC-04.2Keyword search and pagination.
AC-04.3Row actions: View, Edit, Delete according to permissions; bulk delete from selected rows.

US-05 - Delete a role

As an owner, I want to delete roles that are not used.

IDAcceptance criteria
AC-05.1Single and bulk delete require confirmation and the delete permission.
AC-05.2If the deletion is rejected, for example because the role is still in use, the error message appears as a toast.

9. User Scenarios

RoleScenario
OwnerCreates a “Cashier” role that may only access the Sales module
OwnerCreates a “Purchasing” role with all PO actions except Close
AdminChecks the permissions of the “Store Manager” role before assigning it to a new user
OwnerDeletes an old role that is no longer used

10. Permissions & Actions

10.1 Permission by Action

ActionPermissionCondition
View Role Listsettings:role:list:any—
View Role Detailsettings:role:view:any—
Create Rolesettings:role:create:any—
Edit Rolesettings:role:update:any—
Delete Rolesettings:role:delete:any—

11. Notifications

This feature does not trigger any notifications.

12. Dependencies

Related PRDs

  • Users — roles are assigned to users.
  • All modules — every page and action is guarded by a permission key.

Effects on other modules

  • Role changes immediately affect the sidebar menu and the actions available to all users who have that role.
Last updated on