Skip to main content
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). 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: 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 for the full evaluation flow and 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 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 and 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.