UC-BoK AI Context Bundle¶
UC-BoK is a model-driven Unified Commerce Knowledge Platform built on a formal ontology, executable schemas, canonical catalogs and a queryable knowledge graph.
Version: 1.2.0-alpha | Generated: 2026-07-18 | Source: https://github.com/retex-iconic/uc-bok
This page is optimised for pasting into an AI context window or agent tool. Use llms.txt for a lightweight index, or llms-full.txt for raw text.
Ontology Architecture¶
UC-BoK uses a layered ontology:
| Layer | Specification | Purpose |
|---|---|---|
| Business Object Ontology | spec 007 | What exists (46 objects, classifications, relationships) |
| Capability Ontology | spec 008 | What the system can do (25 capabilities) |
| Event Ontology | spec 009 | What happens (107 domain events) |
| Process Ontology | spec 010 | How things happen (15 end-to-end processes) |
| Application Ontology | spec 011 | What applications exist (13 archetypes) |
| Semantic Constraints | spec 012 | What relationships are valid |
| Assessment Framework | spec 014 | How maturity is measured (UCMI 0–4) |
| Experience Model | spec 016 | How actors interact with the system |
Classification vocabulary for Business Objects:
- aggregate-root — transaction boundary, owns lifecycle (e.g., Order, Basket)
- entity — has identity, belongs to aggregate (e.g., OrderLine)
- value-object — immutable, no identity (e.g., Address, Money)
- projection — read-only view (e.g., CustomerSummary)
- reference-data — static/slow-changing (e.g., Store)
Relationship vocabulary (17 canonical labels):
contains, references, triggers, fulfills, validates, projects,
extends, replaces, depends-on, owns, belongs-to, transitions,
notifies, computes, classifies, aggregates, manages
Domains¶
| ID | Name | Mission |
|---|---|---|
customer |
Customer | Manage customer identity profile consent and engagement. |
commerce |
Commerce | Manage basket checkout and commercial interaction. |
order |
Order | Manage commercial commitments and order lifecycle. |
inventory |
Inventory | Manage visibility reservation and allocation of stock. |
fulfillment |
Fulfillment | Manage picking shipping pickup returns and exchanges. |
pricing |
Pricing | Determine selling price and markdowns. |
promotion |
Promotion | Manage promotions coupons and vouchers. |
loyalty |
Loyalty | Manage membership points benefits and rewards. |
payment |
Payment | Manage authorization capture refund and settlement. |
store |
Store | Manage store operations and store execution. |
| --- |
Business Objects (51)¶
| ID | Classification | Domain | Description |
|---|---|---|---|
basket |
aggregate-root | commerce | Commerce container holding intended purchases before order creation. |
basket-line |
entity | commerce | Line-level item entry within a basket. |
catalogue |
aggregate-root | commerce | Curated collection of products made available for sale in one or more channels. |
channel |
entity | commerce | A defined commerce touchpoint through which customers can discover, select, and |
product |
entity | commerce | Sellable item defined by a SKU. The atomic unit of commerce — referenced by ever |
receipt |
aggregate-root | commerce | Customer-facing transaction proof created from a completed sale, payment, return |
subscription |
aggregate-root | commerce | A recurring purchase agreement between a customer and the retailer, automaticall |
address |
value-object | customer | Structured postal address used for shipping, billing, and customer identificatio |
clienteling-session |
aggregate-root | customer | A recorded in-store or digital interaction between a store associate and a custo |
consent |
entity | customer | Customer declaration of agreement or refusal for a specific data processing purp |
customer |
aggregate-root | customer | Canonical party recognized by the enterprise as a customer. |
customer-profile |
entity | customer | Collection of descriptive customer information maintained by the Customer Domain |
customer-segment |
entity | customer | A named group of customers sharing common behavioural, demographic, or value-bas |
decision-record |
aggregate-root | customer | Auditable record of an automated or assisted recommendation, decision, approval, |
sentiment-insight |
aggregate-root | customer | Purpose-bound, aggregated insight derived from approved customer feedback and so |
delivery-slot |
entity | fulfillment | A time-bounded window during which a customer's order can be delivered to a nomi |
exchange |
aggregate-root | fulfillment | Exchange request and execution record for replacing returned merchandise with al |
fulfillment-order |
aggregate-root | fulfillment | Fulfillment-oriented grouping derived from an order for execution. |
picking-task |
aggregate-root | fulfillment | An instruction to locate and collect specific items from a location to fulfil an |
return |
aggregate-root | fulfillment | Return request and execution record for merchandise or order value moving back f |
service-order |
aggregate-root | fulfillment | Customer commitment for repair, installation, maintenance, or other service asso |
shipment |
aggregate-root | fulfillment | Fulfillment movement or collection unit used to complete customer delivery or pi |
shipment-line |
entity | fulfillment | Line-level item entry within a shipment. |
allocation |
aggregate-root | inventory | Assignment of inventory to demand for fulfillment execution. |
inventory |
aggregate-root | inventory | Availability and stock state used to support selling, reservation, allocation, t |
inventory-item |
entity | inventory | Item-level inventory reference used by basket, order, shipment, reservation, and |
reservation |
aggregate-root | inventory | Temporary hold on inventory for a customer, basket, order, or fulfillment flow. |
stock-movement |
entity | inventory | An immutable record of a physical inventory quantity change at a location. |
loyalty-account |
aggregate-root | loyalty | Account used to track loyalty participation state, balances, benefits, and point |
loyalty-member |
aggregate-root | loyalty | A customer enrolled in a loyalty programme who accumulates and redeems points an |
loyalty-transaction |
entity | loyalty | Transaction-level activity that changes or evaluates loyalty account state. |
invoice |
aggregate-root | order | Commercial billing document associated with an order or payment obligation. |
order |
aggregate-root | order | Confirmed commercial commitment created from checkout or assisted selling. |
order-line |
entity | order | Line-level item entry within an order. |
gift-card |
aggregate-root | payment | Stored-value instrument usable as part of payment. |
payment |
aggregate-root | payment | Payment obligation and state associated with a basket, order, return, or exchang |
payment-transaction |
entity | payment | Transaction-level record for payment authorization, capture, void, refund, or se |
refund |
aggregate-root | payment | Payment reversal or credit associated with a return, exchange, or payment correc |
price |
entity | pricing | Monetary value used to sell, calculate, or present an item or basket. |
price-list |
aggregate-root | pricing | Collection or context of prices applied for pricing decisions. |
tax-rate |
entity | pricing | Tax percentage or calculation parameter applied to basket, order, or line values |
coupon |
aggregate-root | promotion | Promotion-related entitlement or code validated and redeemed during selling or c |
promotion |
aggregate-root | promotion | Promotional rule or offer evaluated during basket, checkout, pricing, or selling |
sponsored-offer |
aggregate-root | promotion | Governed retail-media offer with approved audience, placement, timing, and close |
voucher |
aggregate-root | promotion | Value or benefit instrument issued, validated, redeemed, or cancelled. |
employee |
aggregate-root | store | Store or enterprise worker participating in operational processes. |
loss-prevention-case |
aggregate-root | store | Investigable case created from item-identification, transaction, or refund anoma |
store |
aggregate-root | store | Physical retail location participating in selling, fulfillment, returns, exchang |
store-day |
aggregate-root | store | The operational trading period for a physical store on a given date. |
store-task |
entity | store | An operational task assigned to store staff during a trading day. |
terminal |
entity | store | Store endpoint used for point-of-sale or store transaction execution. |
| --- |
Capabilities (33)¶
| ID | Domain | Classification | Outcome |
|---|---|---|---|
customer-identity |
customer | engagement | Customers can be registered, authenticated and uniquely resolved across channels |
customer-profile |
customer | engagement | Customer profile, preferences and contact data can be retrieved and maintained. |
customer-consent |
customer | management | Customer consent records can be created, updated and revoked in compliance with |
customer-segmentation |
customer | intelligence | Customers can be segmented based on behaviour and attributes for targeting and p |
clienteling |
customer | engagement | Store associates can access customer history and record personalised interaction |
basket-management |
commerce | operational | Customers can build, modify and calculate a basket of intended purchases before |
checkout |
commerce | operational | A basket can be converted into a confirmed order by applying promotions, totals |
order-management |
order | management | Orders can be created, validated, confirmed, modified, tracked and closed throug |
order-orchestration |
order | intelligence | Orders can be split, routed and reassigned to optimal fulfilment locations based |
inventory-visibility |
inventory | intelligence | Available-to-promise stock can be calculated and queried by location, SKU and ch |
inventory-reservation |
inventory | management | Inventory can be soft-reserved, confirmed and released across the order and fulf |
inventory-allocation |
inventory | management | Inventory can be hard-allocated, reallocated and released to fulfil specific ord |
store-inventory |
inventory | management | Physical store stock levels can be adjusted, counted and transferred between loc |
fulfillment-execution |
fulfillment | operational | Orders can be picked, packed, shipped, delivered and collected through the physi |
returns-management |
fulfillment | management | Customer returns can be requested, authorised, received, inspected and processed |
exchange-management |
fulfillment | management | Product exchanges can be requested, authorised and processed within the return a |
pricing |
pricing | intelligence | Selling price can be determined and applied based on price lists, rules and mark |
promotions |
promotion | operational | Promotions and coupons can be evaluated and applied to a basket or order to deli |
voucher-management |
promotion | management | Gift vouchers and store credits can be issued, validated, redeemed and cancelled |
loyalty |
loyalty | engagement | Members can be enrolled, earn points and benefits, and redeem rewards across cha |
loyalty-management |
loyalty | management | The loyalty programme configuration, tier definitions, accrual rules, and member |
payment-processing |
payment | operational | Payments can be authorised, captured, voided and refunded independently of payme |
store-operations |
store | management | Store trading days can be opened and closed and daily operational tasks can be a |
catalogue-management |
commerce | management | Product catalogues can be created, enriched, published, and scoped to channels s |
channel-management |
commerce | management | Commerce channels can be configured, activated, and assigned catalogues and pric |
subscription-management |
commerce | management | Customers can create, manage, pause and cancel recurring purchase subscriptions |
guided-selling |
customer | engagement | Associates can deliver explainable, context-aware recommendations that improve t |
decision-intelligence |
customer | intelligence | Material automated decisions can be proposed, reviewed, overridden, executed, an |
social-intelligence |
customer | intelligence | Consent-aware sentiment and engagement insights can inform customer experience d |
automated-item-identification |
inventory | intelligence | Items and identification anomalies can be resolved in real time at store touchpo |
service-order-management |
fulfillment | management | Service and repair commitments can be created, scheduled, fulfilled, and tracked |
retail-media-management |
promotion | intelligence | Sponsored offers can be activated, served, and attributed using consent-aware fi |
loss-prevention |
store | management | Potential retail loss events can be investigated and resolved with auditable, pr |
| --- |
Domain Events (216)¶
Address: AddressAdded, AddressUpdated, AddressValidated
Allocation: InventoryAllocated, InventoryReallocated, InventoryAllocationReleased, AllocationActivated, AllocationUpdated, AllocationFulfilled, AllocationReallocated, AllocationCancelled
Basket: BasketCreated, BasketUpdated, BasketCalculated, BasketCheckedOut, BasketCheckoutStarted, BasketConverted, BasketAbandoned, BasketMerged, CheckoutStarted, CheckoutCancelled
Basket-Line: BasketLineAdded
Catalogue: CataloguePublished, CatalogueUpdated, CatalogueArchived, CatalogueSubmitted, CatalogueApproved, CatalogueRejected, CataloguePublished, CatalogueUnpublished, CatalogueArchived, CatalogueRetired
Channel: ChannelActivated, ChannelUpdated, ChannelDeactivated
Clienteling-Session: ClientelingSessionCreated, ClientelingInteractionRecorded
Consent: CustomerConsentUpdated, CustomerConsentRevoked, ConsentRecorded, ConsentUpdated, ConsentWithdrawn, ConsentDeclined, ConsentExpired
Coupon: CouponValidated, CouponRedeemed
Customer: CustomerRegistered, CustomerIdentified, CustomerMerged, CustomerUpdated, CustomerPreferencesUpdated, CustomerSegmentCalculated, CustomerSegmentAssigned, CustomerCreated, CustomerProfileUpdated, CustomerProfileViewed, CustomerInteractionLogged, CustomerCommunicationSent, CustomerConsentUpdated
Customer-Segment: CustomerSegmentCreated, CustomerSegmentUpdated, CustomerSegmentArchived
Decision-Record: RecommendationGenerated, RecommendationResponded, DecisionProposed, DecisionApproved, DecisionOverridden, DecisionExecuted
Delivery-Slot: DeliverySlotReserved, DeliverySlotConfirmed, DeliverySlotReleased, DeliverySlotExpired
Employee: EmployeeActivated, EmployeeDeactivated, EmployeeOffboarded, EmployeeArchived
Exchange: ExchangeRequested, ExchangeAuthorized, ExchangeCompleted, ExchangeValidated, ExchangeRefused, ExchangeStarted, ExchangeBalanceRequired, ExchangeBalanceSettled, ExchangeCompleted, ExchangeCancelled
Fulfillment-Order: FulfillmentOrderCreated, FulfillmentOrderDispatched
Gift-Card: GiftCardActivated, GiftCardRedeemed, GiftCardToppedUp, GiftCardExpired, GiftCardCancelled, GiftCardRefunded
Inventory: AtpCalculated, InventoryAdjusted, InventoryCounted, InventoryChecked, StockCountOpened, StockCountStarted, StockCountCompleted, StockCountReconciled, StockCountClosed, StockCountRecountRequested, StockCountCancelled, ItemIdentified
Loss-Prevention-Case: ItemIdentificationAnomalyDetected, TransactionAnomalyDetected, LossPreventionCaseOpened, LossPreventionCaseResolved
Loyalty-Account: LoyaltyPointsCalculated, LoyaltyPointsIssued, LoyaltyPointsRedeemed, LoyaltyBenefitsCalculated, PointsIssued, PointsRedeemed, LoyaltyPointsEarned
Loyalty-Member: LoyaltyMemberEnrolled, LoyaltyCardActivated, LoyaltyPointsAccrued
Order: OrderCreated, OrderValidated, OrderConfirmed, OrderModified, OrderCancelled, OrderClosed, OrderSplit, OrderRouted, FulfillmentLocationReassigned
Payment: PaymentAuthorized, PaymentCaptured, PaymentVoided, PaymentRefunded, PaymentSettled
Picking-Task: PickingStarted, PickingCompleted, PickingTaskCreated, PickingTaskCompleted
Price: PriceCalculated, PriceListApplied, MarkdownCalculated
Price-List: PriceListSubmitted, PriceListApproved, PriceListRejected, PriceListActivated, PriceListExpired, PriceListSuperseded, PriceListCancelled
Product: ProductCreated, ProductActivated, ProductUpdated, ProductDeactivated, ProductSearchPerformed
Promotion: PromotionApplied, PromotionEvaluated
Receipt: ReceiptIssued, ReceiptAmended, ReceiptVoided, ReceiptArchived
Refund: RefundCreated, RefundInitiated, RefundProcessed, RefundFailed, RefundConvertedToCredit, RefundCancelled
Reservation: InventoryReserved, ReservationConfirmed, InventoryReleased, ReservationExpired, ReservationCreated, ReservationReleased
Return: ReturnRequested, ReturnAuthorized, ReturnReceived, ReturnInspected, ReturnAccepted, ReturnApproved, ReturnRejected, ReturnDispatched, ReturnRefunded, ReturnExchanged, ReturnCreated
Sentiment-Insight: SentimentInsightProduced
Service-Order: ServiceOrderCreated, ServiceOrderScheduled, ServiceOrderCompleted
Shipment: ShipmentPacked, ShipmentDispatched, ShipmentDelivered, ShipmentCreated, ShipmentLabelGenerated
Sponsored-Offer: SponsoredOfferActivated, SponsoredOfferExposed, SponsoredOfferAttributed
Stock-Movement: InventoryTransferred
Store-Day: StoreDayOpened, StoreDayClosed, StoreDayPreOpeningStarted, StoreDayOpened, StoreDayClosingStarted, StoreDayReconciliationStarted, StoreDayClosed, StoreDayReopened, StoreDayExceptionDeclared
Store-Task: StoreTaskAssigned, StoreTaskCompleted
Subscription: SubscriptionCreated, SubscriptionActivated, SubscriptionRenewed, SubscriptionPaused, SubscriptionCancelled, SubscriptionExpired
Voucher: VoucherIssued, VoucherValidated, VoucherRedeemed, VoucherCancelled¶
Business Processes (26)¶
| ID | Name | Classification |
|---|---|---|
checkout |
Checkout | transactional |
bopis |
BOPIS | transactional |
endless-aisle |
Endless Aisle | transactional |
clienteling-sale |
Clienteling Sale | transactional |
voucher-redemption |
Voucher Redemption | transactional |
ship-from-store |
Ship From Store | fulfilment |
ship-to-store |
Ship To Store | fulfilment |
reserve-and-collect |
Reserve and Collect | fulfilment |
boris |
BORIS | post-sale |
return-anywhere |
Return Anywhere | post-sale |
exchange-anywhere |
Exchange Anywhere | post-sale |
loyalty-enrollment |
Loyalty Enrollment | engagement |
self-checkout |
Self-Checkout | transactional |
customer-registration |
Customer Registration | engagement |
scan-and-go |
Scan and Go | transactional |
price-list-update |
Price List Update | management |
promotional-campaign-launch |
Promotional Campaign Launch | management |
loyalty-tier-upgrade |
Loyalty Tier Upgrade | management |
subscription-renewal |
Subscription Renewal | transactional |
catalogue-publish |
Catalogue Publish | management |
store-day-open |
Store Day Open | management |
customer-consent-update |
Customer Consent Update | management |
decision-review-and-execution |
Decision Review and Execution | management |
loss-prevention-case-handling |
Loss Prevention Case Handling | management |
service-and-repair-management |
Service and Repair Management | post-sale |
retail-media-attribution |
Retail Media Attribution | management |
| --- |
Reference Architectures¶
RA: Fashion Retail Reference Architecture¶
End-to-end unified commerce reference architecture for multi-brand fashion retailers operating across online, in-store, and mobile channels. Models the full capability stack required for seasonal assortment, clienteling, omnichannel fulfilment, and high-volume returns.
RA: Grocery Retail Reference Architecture¶
End-to-end unified commerce reference architecture for grocery and food retailers operating across in-store, click & collect, and home delivery channels. Models the capability stack for high-frequency low-value transactions, fresh/perishable inventory, age verification, multi-buy promotions, and personalised loyalty programmes.
RA: RA-003¶
Unified Commerce reference architecture for specialty retail — knowledge-intensive, service-augmented retail formats where expert selling, product configuration, and post-purchase service are primary revenue and differentiation levers.
RA: Tier 2 Non-food Retail Reference Architecture¶
Vendor-neutral reference architecture for multichannel non-food and softline retailers with a material physical-store estate. POS is an intelligent engagement endpoint within a composable commerce ecosystem; authoritative customer, order, payment, inventory, pricing, and promotion responsibilities remain separated.
UCMI Maturity Index¶
UCMI scores each capability 0–4. Formula: Σ(score × weight) / Σ(weight).
| Score | Band | Description |
|---|---|---|
Run assessment: python scripts/assess.py --profile catalogs/assessment-profiles/<profile>.yaml¶
Key Architectural Rules¶
- Ontology-First — ontologies are defined before catalogs are filled.
- Schema ≠ Semantics — schema says "field exists"; semantics says "relationship is valid".
- Vendor Neutral — no vendor data without SI-led workshop + UCMI scoring (ADR-017).
- Catalog Source of Truth — YAML in
catalogs/; markdown indocs/is publication layer. - Top-Level Directory Rule — a directory = architectural responsibility, not a knowledge domain.
- Success metric — concepts formally defined, validatable and queryable (not catalog count).