> ## Documentation Index
> Fetch the complete documentation index at: https://system.muzemus.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles and permissions

> Complete reference for all roles, their scopes, and permission mappings

## Role hierarchy

```mermaid theme={null}
graph TB
    SA["SUPER_ADMIN<br/>All clients, all data"]
    MA["MUZE_ADMIN<br/>All clients, all data"]
    HR["HR<br/>One client"]
    SM["STORE_MANAGER<br/>One store"]
    EMP["EMPLOYEE<br/>No login (legacy)"]

    SA --> MA
    MA --> HR
    HR --> SM
    SM --> EMP
```

## Role definitions

| Role            | Scope               | Description                                                                                                                            |
| --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `SUPER_ADMIN`   | All clients         | Platform operator. Full access to everything including system settings.                                                                |
| `MUZE_ADMIN`    | All clients         | Operational admin. Full access to all management and reporting functions. Uses the global client selector to choose the active client. |
| `HR`            | One assigned client | Client HR user. Manages employees, approves orders, views reports for their client.                                                    |
| `STORE_MANAGER` | One assigned store  | Store-level operator. Views store employees, places orders, views store-scoped data. Cannot approve orders.                            |
| `EMPLOYEE`      | No login            | Uniform recipient. Orders are placed on their behalf by staff.                                                                         |

> The `EMPLOYEE` role is legacy. Employees are domain records, not platform users. The remaining self-service code path is documented technical debt scheduled for removal in Phase 11.9 and should not be granted to real accounts or built upon.

## Permission groups

The mapping lives in `backend/src/auth/permissions.ts`. Permissions are composed from four groups:

| Group           | Permissions                                                                                                                              | Held by                  |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| Base            | `catalog.view`, `entitlements.view.own`, `orders.create`, `orders.view.own`, `employees.size-profile`                                    | Every authenticated user |
| Scoped manager  | `stores.view`, `regions.view`, `departments.view`, `employees.view`, `entitlements.view`, `orders.view.store`, `reports.replacement-due` | Store Manager, HR        |
| Regional        | `orders.view.all`, `reports.store-ops`, `reports.export`                                                                                 | HR                       |
| HR              | `employees.manage`, `employees.import`, `rule-sets.view`, `orders.approve`                                                               | HR                       |
| All permissions | Everything below                                                                                                                         | Muze Admin, Super Admin  |

## Complete permission catalog

### Catalog and organization

| Permission           | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `catalog.view`       | View uniform categories and products                 |
| `catalog.manage`     | Create, edit, delete uniform categories and products |
| `stores.view`        | View store list and details                          |
| `stores.manage`      | Create, edit, delete stores                          |
| `regions.view`       | View region list and details                         |
| `regions.manage`     | Create, edit, delete regions                         |
| `departments.view`   | View department list                                 |
| `departments.manage` | Create, edit, delete departments                     |

### Employees

| Permission               | Description                            |
| ------------------------ | -------------------------------------- |
| `employees.view`         | View employee list and details         |
| `employees.manage`       | Create, edit, delete employees         |
| `employees.import`       | Bulk import employees via CSV          |
| `employees.size-profile` | View and update employee size profiles |

### Entitlements

| Permission              | Description                                                |
| ----------------------- | ---------------------------------------------------------- |
| `entitlements.view.own` | View own entitlement status                                |
| `entitlements.view`     | View entitlement balances for any employee in scope        |
| `rule-sets.view`        | View entitlement rule set configuration                    |
| `rule-sets.manage`      | Create, edit, delete entitlement rule sets; import via CSV |

### Orders

| Permission             | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| `orders.create`        | Create new orders                                             |
| `orders.view.own`      | View own orders                                               |
| `orders.view.store`    | View all orders for the assigned store                        |
| `orders.view.all`      | View all orders across the client (HR) or all clients (admin) |
| `orders.approve`       | Approve or reject submitted orders                            |
| `orders.status-update` | Update order status through the production pipeline           |
| `orders.delete`        | Delete/cancel orders                                          |

### Reports

| Permission                | Description                         |
| ------------------------- | ----------------------------------- |
| `reports.store-ops`       | View store spend report             |
| `reports.replacement-due` | View replacement-due report         |
| `reports.production`      | View production requirements report |
| `reports.export`          | Export reports as CSV               |

### System and users

| Permission         | Description                             |
| ------------------ | --------------------------------------- |
| `settings.view`    | View system settings                    |
| `settings.manage`  | Modify system settings                  |
| `audit.view`       | View audit log entries                  |
| `users.view`       | View user list                          |
| `users.roles.view` | View user role assignments              |
| `accounts.manage`  | Create, edit, deactivate staff accounts |

There are **33 distinct permissions** covering catalog, organization, employees, entitlements, orders, reports, and system administration.

## Role-permission matrix

| Permission                | EMPLOYEE | STORE\_MANAGER | HR | MUZE\_ADMIN | SUPER\_ADMIN |
| ------------------------- | -------- | -------------- | -- | ----------- | ------------ |
| `catalog.view`            | ✅        | ✅              | ✅  | ✅           | ✅            |
| `catalog.manage`          | —        | —              | —  | ✅           | ✅            |
| `stores.view`             | —        | ✅              | ✅  | ✅           | ✅            |
| `stores.manage`           | —        | —              | —  | ✅           | ✅            |
| `regions.view`            | —        | ✅              | ✅  | ✅           | ✅            |
| `regions.manage`          | —        | —              | —  | ✅           | ✅            |
| `departments.view`        | —        | ✅              | ✅  | ✅           | ✅            |
| `departments.manage`      | —        | —              | —  | ✅           | ✅            |
| `employees.view`          | —        | ✅              | ✅  | ✅           | ✅            |
| `employees.manage`        | —        | —              | ✅  | ✅           | ✅            |
| `employees.import`        | —        | —              | ✅  | ✅           | ✅            |
| `employees.size-profile`  | ✅        | ✅              | ✅  | ✅           | ✅            |
| `entitlements.view.own`   | ✅        | ✅              | ✅  | ✅           | ✅            |
| `entitlements.view`       | —        | ✅              | ✅  | ✅           | ✅            |
| `rule-sets.view`          | —        | —              | ✅  | ✅           | ✅            |
| `rule-sets.manage`        | —        | —              | —  | ✅           | ✅            |
| `orders.create`           | ✅        | ✅              | ✅  | ✅           | ✅            |
| `orders.view.own`         | ✅        | ✅              | ✅  | ✅           | ✅            |
| `orders.view.store`       | —        | ✅              | ✅  | ✅           | ✅            |
| `orders.view.all`         | —        | —              | ✅  | ✅           | ✅            |
| `orders.approve`          | —        | —              | ✅  | ✅           | ✅            |
| `orders.status-update`    | —        | —              | —  | ✅           | ✅            |
| `orders.delete`           | —        | —              | —  | ✅           | ✅            |
| `reports.store-ops`       | —        | —              | ✅  | ✅           | ✅            |
| `reports.replacement-due` | —        | ✅              | ✅  | ✅           | ✅            |
| `reports.production`      | —        | —              | —  | ✅           | ✅            |
| `reports.export`          | —        | —              | ✅  | ✅           | ✅            |
| `settings.view`           | —        | —              | —  | ✅           | ✅            |
| `settings.manage`         | —        | —              | —  | —           | ✅            |
| `audit.view`              | —        | —              | —  | ✅           | ✅            |
| `users.view`              | —        | —              | —  | ✅           | ✅            |
| `users.roles.view`        | —        | —              | —  | ✅           | ✅            |
| `accounts.manage`         | —        | —              | —  | ✅           | ✅            |

The EMPLOYEE column reflects the legacy base permission set described above.