> ## 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 entities > Reference for the core database models 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](/business-engines/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.