Core entities - MUZE Architecture & Technical Documentation

All models live in backend/prisma/schema.prisma, which is the source of truth for exact fields and constraints. This page covers the core domain models.

Organization models

Client

A retail organisation using MUZE (for example Boxer, Clicks).

Field	Type	Description
`id`	String (cuid)	Primary key
`code`	String (unique)	Short client code
`name`	String	Client name
`active`	Boolean	Soft-delete flag
`entitlementEnforcementEnabled`	Boolean	Switches the engine to strict mode. Off (default): free flow, ignoring the INITIAL/REPLACEMENT phase split and classifying excess as employee-paid. On: phase-scoped allocations with over-allocation rejected.
`addressLine1` … `country`	String?	Sales Order delivery address
`contactPerson` / `contactPhone` / `contactEmail`	String?	Onboarding contact

Region

Geographic grouping of stores within a client. Unique on [clientId, code].

Field	Type	Description
`id`	String (cuid)	Primary key
`code` / `name`	String	Region code and name
`clientId`	String	FK to Client (required)
`active`	Boolean	Soft-delete flag

Store

A retail location. Requires a client and a region.

Field	Type	Description
`id`	String (cuid)	Primary key
`storeNumber`	String (unique)	Store identifier
`name`	String	Store name
`clientId`	String	FK to Client (required)
`regionId`	String	FK to Region (required)
`address` / `division` / `areaManager`	String?	Optional store details
`managerEmail` / `managerContactNumber`	String?	Store manager contact
`rolloutAnchorDate`	DateTime?	Entitlement cycle anchor for the store
`active`	Boolean	Soft-delete flag

Department

Organisational unit within a client, used as entitlement criteria. Unique on [clientId, code].

Field	Type	Description
`id`	String (cuid)	Primary key
`code` / `name`	String	Department code and name
`clientId`	String	FK to Client (required)
`active`	Boolean	Soft-delete flag

Access models

User

A staff portal account (better-auth user).

Field	Type	Description
`id`	String	Primary key
`name` / `email`	String	Display name and login email (unique)
`emailVerified`	Boolean	Set true after invite/password-reset flow
`phoneNumber`	String?	Optional phone
`accountStatus`	AccountStatus	`PENDING_ACTIVATION`, `ACTIVE`, or `DISABLED`
`themePreference`	ThemePreference?	UI theme

UserRole

Links a user to a role with optional scope. A user can hold multiple roles.

Field	Type	Description
`id`	String (cuid)	Primary key
`userId`	String	FK to User
`role`	Role	`SUPER_ADMIN`, `MUZE_ADMIN`, `HR`, `STORE_MANAGER`, `EMPLOYEE`
`clientId`	String?	FK to Client (set for HR scope)
`storeId`	String?	FK to Store (set for Store Manager scope)
`regionId`	String?	FK to Region (optional)

Session

better-auth session storage.

Field	Type	Description
`id`	String	Primary key
`userId`	String	FK to User
`token`	String (unique)	Session token
`expiresAt`	DateTime	Expiration

Catalog models

UniformCategory

Groups employees who share entitlement rules. Each employee belongs to exactly one category. Client-scoped.

Field	Type	Description
`id`	String (cuid)	Primary key
`name` / `description`	String	Category name and description
`clientId`	String	FK to Client
`active`	Boolean	Soft-delete flag

Product

An individual uniform item available for ordering. Unique on [clientId, code].

Field	Type	Description
`id`	String (cuid)	Primary key
`code`	String	Product code
`name`	String	Display name
`type`	ProductType	Golfer, Shirt, Trousers, Jacket, Safety Shoe, and other garment types
`colour` / `description`	String?	Optional details
`price`	Decimal	Price in cents
`imageUrl`	String?	Product image
`companyAllocationEligible`	Boolean	Whether the product can be company-paid. Default false.
`sizes`	ProductSize[]	Available sizes
`active`	Boolean	Soft-delete flag

Employee models

Employee

A uniform recipient. Employees have no portal login; userId is a legacy link kept for technical-debt removal (Phase 11.9).

Field	Type	Description
`id`	String (cuid)	Primary key
`employeeNumber`	String (unique)	Employee identifier
`firstName` / `surname`	String	Name
`employmentStartDate`	DateTime	Drives entitlement phase calculation
`employmentType`	EmploymentType	`PERMANENT`, `CASUAL`, `CONTRACT`
`storeId`	String	FK to Store (required)
`uniformCategoryId`	String	FK to UniformCategory (required)
`departmentId` / `jobTitle` / `managerId`	String?	Optional organisational assignment
`contactNumber` / `email` / `idNumber`	String?	Optional details
`active`	Boolean	Soft-delete flag

EmployeeSizeProfile

One per employee (employeeId unique).

Field	Type	Description
`shirtSize` / `trouserSize` / `jacketSize` / `shoeSize`	String?	Garment sizes

Entitlement models

EntitlementRuleSet

Defines entitlements for a uniform category. Client-scoped.

Field	Type	Description
`id`	String (cuid)	Primary key
`name`	String	Rule set name
`clientId`	String	FK to Client
`effectiveFrom` / `effectiveTo`	DateTime	Effective period
`approvalRequired`	Boolean	Whether orders under this rule set need approval. Default false.
`replacementCycleMonths`	Int	Replacement cycle length. Default 24.
`items`	EntitlementRuleItem[]	Allocated products
`criteria`	EntitlementRuleCriteria[]	Employee matching conditions
`active`	Boolean	Soft-delete flag

EntitlementRuleItem

One allocated product within a rule set.

Field	Type	Description
`ruleSetId`	String	FK to EntitlementRuleSet
`productId` / `productCode`	String?	The product (or code) being allocated
`allocationPhase`	AllocationPhase	`INITIAL`, `REPLACEMENT`, or `BOTH`
`quantity`	Int	Quantity per cycle
`paymentEligibility`	PaymentType	`COMPANY_PAID` (default) or `EMPLOYEE_PAID`

EntitlementRuleCriteria

One criteria row for matching employees to a rule set.

Field	Type	Description
`entitlementRuleSetId`	String	FK to EntitlementRuleSet
`attribute`	CriteriaAttribute	`department`, `store`, `employmentType`, `jobTitle`
`operator`	CriteriaOperator	`IN`, `NOT_IN`, `CONTAINS`
`values`	Json	Values to match against

EntitlementPeriod

One allocation cycle for one employee against one rule set. Consumption is tracked through the period’s order items.

Field	Type	Description
`employeeId` / `ruleSetId`	String	FKs to Employee and EntitlementRuleSet
`periodType`	PeriodType	`INITIAL` or `REPLACEMENT`
`status`	PeriodStatus	`PENDING`, `ACTIVE`, `RESERVED`, `CONSUMED`, `EXHAUSTED`, `CANCELLED`
`startDate` / `endDate`	DateTime	Cycle window
`eligibilityDate`	DateTime	When the employee becomes replacement-eligible
`orderItems`	OrderItem[]	Consumption recorded against this period

Order models

Order

A uniform order for one employee, placed by a staff user.

Field	Type	Description
`id`	String (cuid)	Primary key
`orderNumber`	String (unique)	`ORD-YYYYMMDD-NNNN` (prefix configurable)
`storeOrderId`	String?	FK to StoreOrder batch
`employeeId` / `storeId`	String	FKs to Employee and Store
`submittedById`	String	FK to User who placed the order
`status`	OrderStatus	12 status values (see Order lifecycle)
`submittedAt` / `approvedAt` / `rejectedAt` / `deliveredAt`	DateTime	Lifecycle timestamps
`rejectedReason`	String?	Required rejection reason
`notes`	String?	Order notes

OrderItem

One product line within an order.

Field	Type	Description
`orderId` / `productId`	String	FKs to Order and Product
`size` / `quantity`	String / Int	Size and quantity
`unitPrice`	Decimal	Price captured at order time
`paymentType`	PaymentType	`COMPANY_PAID` or `EMPLOYEE_PAID`
`entitlementPeriodId`	String?	Period this item consumed
`entitlementQuantityConsumed`	Int	Quantity counted against the entitlement balance

OrderStatusHistory

Audit trail of status changes.

Field	Type	Description
`orderId`	String	FK to Order
`fromStatus` / `toStatus`	OrderStatus	Transition (from is null for the initial entry)
`changedById`	String?	FK to User
`note`	String?	Change note
`changedAt`	DateTime	Timestamp

StoreOrder

Groups the orders from one submission into a batch, tied to a single store.

Field	Type	Description
`storeOrderNumber`	String (unique)	`SO-XXXXX` (prefix configurable)
`storeId`	String	FK to Store
`orders`	Order[]	Member orders

System models

Notification

In-app and email notification records, linked to a recipient user.

Field	Type	Description
`recipientId`	String	FK to User
`type` / `title` / `body`	String	Notification content
`channel`	NotificationChannel	`IN_APP`, `EMAIL`, or `WHATSAPP` (reserved)
`status`	NotificationStatus	Delivery state
`readAt`	DateTime?	When marked read
`relatedType` / `relatedId`	String?	Linked entity (for example an order)

EmailLog

Audit record of every email attempt, including provider response and errors.

AuditLog

Field	Type	Description
`actorId`	String?	FK to User
`action` / `entityType` / `entityId`	String	What was done to which record
`before` / `after`	Json?	Previous and new state

ImportBatch

Tracking record for each bulk import: kind, file name, total/success/error row counts, and per-row errors.

SystemSetting

Key-value configuration (key unique), grouped by concern. Includes ORDER_NUMBER_PREFIX, STORE_ORDER_NUMBER_PREFIX, and notification toggles.

NumberSequence

Persistent counter backing order and store-order number generation.

Supporting models

Account and Verification (better-auth), NotificationTemplate, and InventoryStockLevel complete the schema. See schema.prisma for their fields.

​Organization models

​Client

​Region

​Store

​Department

​Access models

​User

​UserRole

​Session

​Catalog models

​UniformCategory

​Product

​Employee models

​Employee

​EmployeeSizeProfile

​Entitlement models

​EntitlementRuleSet

​EntitlementRuleItem

​EntitlementRuleCriteria

​EntitlementPeriod

​Order models

​Order

​OrderItem

​OrderStatusHistory

​StoreOrder

​System models

​Notification

​EmailLog

​AuditLog

​ImportBatch

​SystemSetting

​NumberSequence

​Supporting models