> ## 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.

# Core concepts

> The domain concepts that shape every part of MUZE

Every table, API endpoint, and UI screen in MUZE maps back to one of the concepts below. Read this page before the implementation sections.

## Multi-client tenancy

MUZE is a B2B platform. Each retail client (for example Boxer, Clicks) is a `Client` entity in the database. Every data-bearing row is scoped to a `clientId`, and a single deployment serves all clients. There is no per-client database isolation; isolation is enforced at the application layer (see [Client isolation](/security/client-isolation)).

In practice:

* A Super Admin or Muze Admin sees data across all clients and uses the global client selector to pick the active client.
* An HR user sees data only within their assigned client.
* A Store Manager sees data only within their assigned store.

## Staff-only portal

Employees are the subjects of the system: uniforms are ordered on their behalf. They never log in. Only staff roles authenticate:

| Role            | Scope               | Can approve orders? |
| --------------- | ------------------- | ------------------- |
| `SUPER_ADMIN`   | All clients         | Yes                 |
| `MUZE_ADMIN`    | All clients         | Yes                 |
| `HR`            | One assigned client | Yes                 |
| `STORE_MANAGER` | One assigned store  | No                  |
| `EMPLOYEE`      | No login            | No                  |

A legacy `Role.EMPLOYEE` self-service code path still exists in the backend as documented technical debt. It is scheduled for removal (Phase 11.9) and should not be treated as a supported feature or built upon.

## Uniform categories

A uniform category groups **employees who share the same entitlement rules**, for example "Store Management" or "Boxer Stores - Flexi Hourly Paid Employees". Each employee belongs to exactly one category. Categories are client-scoped.

A **product** is an individual uniform item (for example a shirt or safety boot) with a type, colour, price, and size list. Products belong to a client. Rule sets allocate products, not categories.

## Rule sets and entitlements

A **rule set** defines what a uniform category is entitled to:

* An effective period (`effectiveFrom` / `effectiveTo`)
* A replacement cycle in months (default 24)
* Whether orders placed under it require approval (`approvalRequired`)
* **Rule items**: which products, how many, in which phase (INITIAL, REPLACEMENT, or BOTH), and with which payment eligibility (COMPANY\_PAID or EMPLOYEE\_PAID)
* **Criteria**: employee attribute conditions (department, store, employment type, job title) that decide which rule set applies to which employee

An **entitlement period** is the per-employee record of one allocation cycle for a matched rule set. Its status moves from PENDING through ACTIVE to CONSUMED or EXHAUSTED. Consumption is tracked per order item against the active period, so an employee's remaining balance is `allowed quantity - consumed quantity` for each product.

The engine evaluates rule sets against employee facts at order time. See the [Entitlement engine](/business-engines/entitlement-engine) for the full evaluation flow and [Replacement system](/business-engines/replacement-system) for cycle timing.

## Orders

An order represents a uniform request for one employee, linked to an employee, a store, and a uniform category. Orders follow a strict lifecycle with server-enforced status transitions; no order can bypass it.

Key facts:

* Individual order numbers follow `ORD-YYYYMMDD-NNNN` (daily sequence; prefix configurable via the `ORDER_NUMBER_PREFIX` system setting)
* Store order batches use `SO-XXXXX` (global sequential; prefix configurable via `STORE_ORDER_NUMBER_PREFIX`)
* Orders submitted from one store are grouped under a store order batch, which HR approves and admins advance as a group

See [Order lifecycle](/business-engines/order-lifecycle) for the status flow.

## Approval

When the matched rule set sets `approvalRequired: true`, an order enters `PENDING_APPROVAL` and must be approved by an HR user or admin before production. Rule sets without the flag submit directly. The `ORDERS_APPROVE` permission is held only by HR, Muze Admin, and Super Admin.

## Data scoping

The `ScopeGuard` enforces data boundaries at the API level. A Store Manager calling an endpoint with a `storeId` parameter can only reference their assigned store. An HR user can access any store within their client. Admins bypass scope checks. Query-level filtering happens in the service layer. See [Authorization](/security/authorization) and [Data scoping](/security/data-scoping).

## Size profiles

Each employee has a size profile (shirt, trouser, jacket, shoe sizes) set by staff. Profiles pre-fill the correct sizes during ordering.