# Domain Vocabulary

## Catalog
* **Product**: The abstract definition of a fragrance, textile, or accessory (e. Includes a list of applicable countries (UAE, Saudi, Qatar, Oman, Bahrain, Kuwait). Priced in AED; auto-converted to local currency on the storefront using fixed exchange rates.g., "Aged Indian Oud", "Rose Blend"). Contains a collection of ordered `ProductImage`s for visual representation. Bilingual attributes (`En` / `Ar`) are used for localization.
* **Rating**: An integer score (1-5) left by a `User` for a `Product`. A user can only rate a product if they have an `Order` containing a variant of that product with a status other than `Pending Payment`. Stored as a single upsertable record per User+Product pair. `averageRating` and `ratingCount` are cached on the `Product`.
* **Variant**: A specific configuration of a Product, often representing volume or weight (e.g., "1 Tola", "50ml", "Size M"). A single-dimensional descriptive string. Contains a `unitCost` representing the current base cost to produce or acquire this item.
* **Category**: A thematic grouping of Products (e.g., "Oud", "Blends", "Incense", "Products from Mumbai"). A flat structure (no sub-categories) where a Product can belong to multiple Categories. Used to group items by type or origin. Categories are globally ordered using a `sortOrder` for display consistency across the storefront.
* **SKU (Stock Keeping Unit)**: A unique identifier tied to a Variant.
* **Inventory**: Tracked physically using a `stockQuantity` on each Variant.

## Sales
* **User**: A customer who authenticates via Email and Password. Tied to their Orders.
* **Order**: A confirmed commitment by a Customer to purchase a specific set of items. Every Order belongs to exactly one authenticated User. Contains customer shipping and contact details. Stores snapshotted financial totals (`subtotalAmount`, `shippingCost`, `totalAmount`) to preserve historical accuracy. Automatically applies hardcoded discount rules (10% first order discount applied to the subtotal) during calculation.
  * *Reconciliation*: Orders in `Pending Payment` status for less than 48 hours are regularly checked against the payment gateway to catch missed webhooks. If the gateway reports `Paid` with a matching amount, the order auto-corrects to `Paid` and allocates inventory. If amounts mismatch, it moves to `Requires Review`.
  * *Abandonment*: Orders remaining in `Pending Payment` beyond 48 hours are automatically moved to an `Abandoned` status.
  * *Inventory Allocation*: Inventory is *only* reduced (allocated) when an order successfully reaches the `Paid` status, never before.
* **Line Item**: A single entry on an Order, representing one Product Variant and its quantity. Snapshots the `unitCost` at the time of purchase for accurate historical profit calculation. Contains an optional `note` for specific item alterations, and a flexible `attributes` JSON payload for dynamic custom fields (like physical measurements: shoulder, bust, hand, etc.).
* **Shipping Method**: A delivery option chosen for an Order (e.g., "Express Delivery"). Contains base details (name, price) and can be deactivated instead of deleted to preserve history.
* **Fulfillment**: The lifecycle of preparing an Order for the Customer. Statuses progress from `Pending` -> `Processing` -> `Shipped`.

## Metrics
* **Total Products**: The count of abstract `Product` entities, not physical inventory items.
* **Total Assets**: The count of all globally managed `Asset` media records.
* **Total Orders**: The count of `Order` records that have advanced beyond `Pending Payment` (i.e., `Paid`, `Processing`, `Shipped`).
* **Total Revenue**: The sum of `totalAmount` collected from all valid `Order`s (statuses `Paid`, `Processing`, `Shipped`).

## Storefront Content
* **Asset**: A globally managed media file (e.g., an uploaded image). Can be uploaded independently and later linked to various entities (Products, Homepage Banners, etc.).
* **HomePageSection**: An ordered building block of the storefront's home page (e.g., "Hero Banner", "Featured Categories", "New Arrivals").
  * Stores configuration in a flexible `payload` (JSONB) instead of strict relational links.
  * Hydrated dynamically by the backend. Missing or deleted linked items (like a deleted Product SKU) are silently ignored during hydration rather than throwing errors.
* **Static Page**: Informational pages like Privacy Policy or About Us. Identified by a fixed `key` rather than a dynamic slug, allowing the admin to edit content (title, description, in both English and Arabic) but not create arbitrary new pages.
* **Contact Inquiry**: A record of a customer request from the storefront (such as booking the "Atelier" private viewing), containing customer contact info and their message.

## Search & Filtering
* **Storefront Filtering**: Customer-facing criteria used to narrow down the Catalog. Distinct from Admin Search. Usually includes facets like Price ranges, available Variants (Sizes/Colors), in-stock Inventory (hiding "Sold Out" items where all variants have 0 stock), and sorting by attributes like "Best Seller" (tracked via a `salesCount` on the Product), Newest, Price, and Discount.
* **Admin Search**: Backend queries used by the administrative panel to find and audit records. Typically filters by text matches (e.g., searching by name), internal system data like creation `startDate` and `endDate`, and inventory status (like `hideSoldOut`).

## Technical Boundaries
* **Money**: Represented internally as integers (smallest currency unit, e.g., fils/cents) to prevent rounding errors. The system operates on a single base currency defined globally.
* **Shipping Region**: A geographic grouping of cities/countries (e.g., `MAIN_UAE`, `WESTERN`, `GCC`). Regions are mapped 1-to-1 with a `ShippingMethod` record via the `regionCode` field to establish their dynamic base shipping cost. The list of cities belonging to each region is hardcoded in the application layer, not the database.
* **Global Configuration**: A singleton store (e.g., table or document) holding platform-wide settings like base currency, branding (logo, name), and social links.
* **Persistence**: MySQL is the primary data store. No complex EAV tables are used; standard relational tables handle core entities. JSON is used where flexible schema is needed.
* **Authentication**: JWT-based authentication specifically scoped for Admin users managing the platform.
* **Asset Storage**: Images and media are stored locally on the server filesystem, served via static routes, rather than an external object store (like S3).
* **3PL**: Third-Party Logistics. The external system (if any) responsible for physically shipping the goods. Our system treats this as an abstract boundary.