Domain Model Map (Business-Level)

This page summarizes the business entities and relationships across the headless stack. It is descriptive only; it does not define APIs or implementation details. Entity names are conceptual and may be refined during contract drafting.

Cross-service relationship map (conceptual)

graph TD
    UAS["UAS<br/>User Accounts"] --> USM["USM<br/>Sessions & API Keys"]
    USM --> OFM["OFM<br/>Orgs & Facilities"]
    OFM --> PVM["PVM<br/>Products & Vendors"]
    PVM --> PMC["PMC<br/>Publish Control"]
    PMC --> PPM["PPM<br/>Pricing & Promos"]
    PPM --> SCM["SCM<br/>Sales Cycle"]
    SCM --> ICS["ICS<br/>Inventory"]
    ICS --> Accounting["ACCT<br/>Accounting"]
    SCM --> Influencer["IFM<br/>Influencer"]
    CRM["CRM<br/>Customer & Loyalty"] --> SCM
    PCM["PCM<br/>Procurement"] --> PVM
    PCM --> ICS
    ExtMaster["External Master Data"] -.-> PVM
    ExtMaster -.-> PCM
    IPM["IPM<br/>Integration Plane"] --> RBS["RBS<br/>Retail Bus"]
    MRS["MRS<br/>Metarecords"] -.-> PVM

System-of-record responsibilities (business)

These boundaries prevent duplicated truth and make audit trails reliable.

Domain	System of record	Notes
Product truth	PVM	Canonical product structure, suppliers, taxonomy, variants.
Sellability by channel	PMC	Published, versioned channel listings and online status.
Temporal pricing	PPM	Effective‑dated price rules and resolved price snapshots.
Inventory positions	ICS	Stock positions, reservations/allocations/commits, stock card.
Sales transactions	SCM	Orders, fulfillment, returns, and tender records.
Procurement transactions	PCM	POs, receipts, invoices, RTV, and NPI initiation.
Customer & loyalty	CRM/Loyalty	Customer accounts, consent, loyalty and stored value ledgers.
Influencer attribution	Influencer	Attribution rules, earnings, and payout readiness.
Accounting exports	Accounting	Derived financial event views and reconciliation outputs.

Channel surfaces (sales and procurement) provide carts/worksheets and context inputs, but they do not own transaction truth.

Search-plane policy (specified)

• Partial-match search must use a dedicated search plane (no full-table scans).
• Required partial search: PMC (catalog), CRM (customers/contacts), SCM (orders/returns by external refs).
• Optional partial search (policy-defined): PPM (price lists/rules), Influencer (profiles/campaigns).
• Exact-match only by default: ICS and PCM (unless a search-plane index is explicitly approved).
• All search is org-scoped; facility/channel filters are required when applicable.
• Search results must honor anti-enumeration and role visibility.

Search-plane operational model (minimum)

• Indexing latency: targets are defined in /common/performance-slos.html (p95 ≤ 30s, p99 ≤ 2m).
• Reindex strategy: versioned indexes with dual-write during migrations; full rebuilds use backfill jobs with progress visibility.
• Consistency behavior: during rebuilds, searches may be stale but must remain bounded and org-scoped; fall back to exact-match queries when required.
• Degradation rules: if search is unavailable, operational workflows must fail with a clear error; non-critical analytics can defer.

Inventory Control (ICS)

Entities:

• Stock position (variant + logical facility + bin/zone)
• Location hierarchy (facility -> zone -> bin; includes staging, receiving, shipping, quarantine)
• Stock card event (immutable change record with reason, actor, comments, and source references)
• Reservations, allocations, commitments (channel-aware)
• Transfer request and transfer shipment
• Counts and adjustments (cycle/physical)
• Ownership/possession states (own+possess, own-not-possess, possess-not-own, in-transit)

Relationships:

• Stock position belongs to a logical facility and references a PVM variant.
• Stock card events reference source transactions (PO/receipt/transfer/sale/adjustment).
• Transfer requests produce one or more shipments and stock card entries at both origin and destination.

Historical and as-of requirements:

• ICS must support as-of queries for stock positions and stock card history for >= 24 months in hot access.
• Historical reads must be served from materialized state + snapshots (no unbounded event replays).
• Projections beyond 24 months may use slower analytics paths.

Sales Cycle Management (SCM)

Entities:

• Sales channel cart (channel-owned; referenced by SCM orders)
• Sales order and order line
• Fulfillment plan (split by facility and modality)
• Shipment, delivery, pickup (BOPIS/curbside)
• Return/RMA and disposition
• Tender records (gift cards, store credits, on-account, etc.)

Relationships:

• Orders reference PMC sellable listings (published revision context).
• Orders reserve/allocate stock via ICS and capture price snapshots from PPM.
• Returns feed ICS stock adjustments and Accounting events.

Procurement Cycle Management (PCM)

Entities:

• Procurement channel worksheet (channel-owned; referenced by PCM POs)
• Purchase order and PO line (including runs/matrix ordering)
• Receipt, ASN, and exception record
• Invoice and match (2-way/3-way)
• RTV and vendor credit

Relationships:

• PO lines reference PVM products and supplier master references.
• Receipts and exceptions create ICS stock card events.
• PCM can initiate product build-up in PVM (NPI).

Pricing and Promotions (PPM)

Entities:

• Price policy and price book (org default with facility/channel overrides)
• Price list entries (temporal, effective-dated)
• Promotion and discount rules (coupon, employee, influencer, customer tier)
• Price snapshot (captured at order/quote time)

Relationships:

• Price policies apply to PVM variants and PMC listings by channel and facility.
• SCM uses price snapshots for orders and quotes; PCM may use price context for cost comparisons.

Historical and as-of requirements:

• Price resolution and price snapshots must be queryable as-of any time within >= 24 months.
• Historical reads use snapshots/materialized views; do not depend on unbounded event playback.
• Projections (future price modeling) may be slower and async.

CRM and Loyalty

Entities:

• Customer account, contact, and consent/preferences
• Loyalty account, points ledger, rewards/redemptions
• Gift card and store credit ledgers

Relationships:

• Customer accounts link to SCM orders and returns.
• Loyalty and stored value balances update from sales and returns.

Influencer/Affiliate

Entities:

• Influencer profile and attribution identifiers
• Campaign and attribution rules
• Earnings ledger and payout statements
• Holds, clawbacks, and fraud flags

Relationships:

• SCM orders generate attribution events tied to sales channels.
• Accounting consumes earnings ledger for payable/liability reporting.

Accounting/ERP Readiness

Entities:

• Financial event (sales, refunds, taxes, inventory movements, procurement liabilities, commissions)
• Export batch and settlement references
• Cost-centre attribution and facility/channel dimensions

Relationships:

• All services emit accounting-ready events with traceability to source transactions.
• Events are facility-first with org rollups for reporting.

External Master Data (global reference plane)

Entities:

• Supplier master reference
• Product master reference

Relationships:

• PVM and PCM may reference global master data but cannot modify it.
• Orgs may store annotations/mappings to immutable, versioned master references.

Entity Relationship Diagrams (contract-level)

Field names are sourced from OpenAPI component schemas. These diagrams show key relationships only; see per-service docs for full schemas.

Product Domain (PVM + PMC)

erDiagram
    Division ||--o{ Department : contains
    Department ||--o{ Category : contains
    Category ||--o{ Category : "parent (tree)"
    Category ||--o{ Style : "category_id"
    Style ||--o{ Variant : "style_id"
    Style }o--|| Vendor : "vendor_primary"
    Style }o--|| Manufacturer : "manufacturer_primary"
    Style }o--o| OGM : "ogm_id"
    Style }o--o| Brand : "brand_id"
    Variant ||--o{ Identifier : "variant_id"
    Variant ||--o{ Barcode : "variant_id"

    Division {
        string division_id
        string code
        string caption
        string status
    }
    Department {
        string department_id
        string division_id
        string code
        string status
    }
    Category {
        string category_id
        string department_id
        string parent_category_id
        string code
        string status
    }
    Style {
        string style_id
        string code
        string category_id
        string ogm_id
        string brand_id
        string status
    }
    Variant {
        string variant_id
        string style_id
        string code
        string signature
        string status
    }
    Vendor {
        string vendor_id
        string code
        string status
    }
    Manufacturer {
        string manufacturer_id
        string code
        string status
    }

Sales Domain (SCM)

erDiagram
    Order ||--o{ OrderLine : contains
    Order ||--o{ Shipment : fulfills
    Order ||--o{ Return : "return for"
    Order }o--|| Quote : "from quote"

    Order {
        string order_id
        string status
        string channel_code
        string logical_guid
        string customer_ref
    }
    OrderLine {
        string line_id
        string variant_id
        string sku
        number qty
    }
    Shipment {
        string shipment_id
        string status
        string order_id
    }
    Return {
        string return_id
        string status
        string order_id
    }
    Quote {
        string quote_id
        string status
        string channel_code
    }

Inventory Domain (ICS)

erDiagram
    StockPosition }o--|| Zone : "zone_code"
    StockPosition }o--o| Bin : "bin_code"
    TransferRequest ||--o{ TransferShipment : ships
    Zone ||--o{ Bin : contains

    StockPosition {
        string variant_id
        string logical_guid
        string zone_code
        string bin_code
        object buckets
        number average_cost
    }
    Zone {
        string zone_id
        string zone_code
        string logical_guid
        string status
    }
    Bin {
        string bin_id
        string bin_code
        string zone_code
        string status
        string bin_type
    }
    TransferRequest {
        string transfer_id
        string status
        string source_logical_guid
        string dest_logical_guid
    }

Procurement Domain (PCM)

erDiagram
    PurchaseOrder ||--o{ POLine : contains
    PurchaseOrder ||--o{ Receipt : received_by
    Receipt ||--o{ Invoice : "invoiced via"

    PurchaseOrder {
        string po_id
        string status
        string logical_guid
        string vendor_ref
    }
    POLine {
        string line_id
        string variant_id
        string sku
        number qty
        number unit_cost
    }
    Receipt {
        string receipt_id
        string status
        string po_id
    }
    Invoice {
        string invoice_id
        string status
        string vendor_ref
        string po_id
    }