Skip to main content

Domain model

Core entities developers touch when extending catalog, stock, POS, ecommerce checkout, or shareable customer links. Source of truth: Django models under backend-main/.

Entity map​

erDiagram
  Warehouse ||--o{ WarehouseStock : holds
  Product ||--o{ WarehouseStock : stocked_as
  Product }o--o| Category : categorized
  PointOfSale }o--o{ Warehouse : serves
  PointOfSale ||--o{ POSOrder : places
  POSOrder ||--o{ POSOrderItem : contains
  POSOrder }o--o| CustomerLink : from_link
  Product ||--o{ POSOrderItem : line
  EcommerceSettings }o--o| PointOfSale : fulfillment_pos
  PendingRazorpayCheckout }o--o| POSOrder : fulfilled_as
  PointOfSale ||--o{ CustomerLink : owns
  CustomerLink ||--o{ CustomerLinkProduct : lines
  CatalogLink }o--o| CustomerLink : consumes_into
  PointOfSale ||--o{ CatalogLink : owns
  CatalogLink }o--o{ Product : includes

Catalog & stock​

Product — warehouse/models.py (backend-main/warehouse/models.py)​

Global catalog SKU: name, slug, image, optional Category / PricingCategory, sku, default_price, customizable, dimensions, is_addon, show_in_pos_catalog, soft activity via is_active.

Property metadata uses ProductPropertyKey / ProductPropertyValue / ProductPropertyAssignment (Brand/Model-style facets).

Warehouse / WarehouseStock​

  • Warehouse — physical location (name, location, is_active).
  • WarehouseStock — unique (warehouse, product) with integer quantity.
  • Related audit: StockHistoryEntry, StockTransfer / StockTransferItem.

Note: Ecommerce checkout decrements stock on COD / Razorpay fulfillment (ecommerce/services.py (backend-main/ecommerce/services.py)). POS order create does not decrement warehouse stock today (report.md §2.4) — treat as a known inventory inconsistency unless fixed later.

POS terminals & orders​

PointOfSale — pos/models.py (backend-main/pos/models.py)​

Store terminal: slug, shop branding, M2M warehouses, password hash, rotating access_key, store address, UPI QR, default service charge, per-POS POSPricingCategoryPrice overrides.

POSOrder / POSOrderItem​

Unified order record for both POS and ecommerce:

FieldRole
order_idAllocated PREFIX-DDMMYYYY-##### (ECOMM for ecommerce; POS name-derived prefix otherwise)
posOwning terminal
order_sourcepos | ecommerce
statusOrder-level lifecycle (see Order lifecycle)
payment_statusAdmin payment sub-status (independent of status)
payment_methodcod / razorpay (ecommerce); blank for typical POS
customer_linkOptional FK when converted from a customer link
customer_emailUsed heavily for ecommerce

Items snapshot product name/image/price; support custom images, designs, service-charge lines, and per-unit workflow (POSOrderItemWorkflowUnit).

Ecommerce​

EcommerceSettings — ecommerce/models.py (backend-main/ecommerce/models.py)​

Singleton (pk=1): store enable flag, utility bar copy/color, default shipping cost, COD/Razorpay toggles, optional FK to fulfillment PointOfSale.

Supporting ecommerce models (not exhaustive): EcommerceWarehouse, EcommerceProductListing, banners, EcommerceCustomer / addresses, reviews, SEO entries, static pages.

PendingRazorpayCheckout​

Cart snapshot waiting for Razorpay capture. Fields: razorpay_order_id, amount, JSON snapshot, status (open | fulfilled), optional OneToOne pos_order after fulfillment.

No POSOrder exists until payment succeeds (ecommerce/checkout_orders.py (backend-main/ecommerce/checkout_orders.py)). Abandoned open rows are not auto-expired today — Verify ops cleanup if needed (report.md §4).

Customer & catalog links​

CustomerLink — customerlink/models.py (backend-main/customerlink/models.py)​

Shareable POS-created checkout session:

  • IDs: sequential link_id, URL-safe link_code
  • Statuses: Empty → Submitted → Order Placed (plus Archived)
  • source: customer_link | catalog
  • Shipping + payment screenshot fields; step1/2/3 completion flags
  • Lines: CustomerLinkProduct (optional product/design/addons)
  • Chat: CustomerLinkComment (Admin / Customer / System)

Public URL builder: CustomerLink.url → checkout frontend via config/public_urls.py (backend-main/config/public_urls.py).

POS-scoped catalog slice: M2M categories, design collections, and/or explicit products; optional CatalogLinkPrice overrides. On submit, creates a CustomerLink (source=catalog, status Submitted) and sets consumed_at / OneToOne customer_link (customerlink/catalog_views.py (backend-main/customerlink/catalog_views.py)).

Designs (supporting)​

designcatalog/models.py (backend-main/designcatalog/models.py): DesignCollection → DesignGroup → Design. Referenced from ecommerce listings, POS catalog, and customer/catalog link line items (design_* snapshot fields on order/link products).