Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
Ring Platform ships a multi-vendor marketplace: any verified Entity can onboard as a vendor, list products, and earn after paid orders settle. Buyers browse a cached catalog, hold a cart, then check out through authenticated order + PaymentConductor rails. Vendors enrich catalog copy with Agent Knowledge Research (WebConductor → fields, markdown, Admin Wiki NODUS, File Cabinet alt images) and opt media into the gallery explicitly.
Use the Founder / Developer tabs in the docs sidebar to filter this page. Cart and checkout below match features/store + app/api/store/* in Layer1 — do not invent extra cart REST beyond the verified session mirror.
| Concern | Where it lives | Notes |
|---|---|---|
| Catalog SSOT | getCachedProductCatalog() → GET /api/store/products | 'use cache' + cacheTag('store:products'); invalidate with updateTag after create |
| Guest cart | localStorage key ring_cart | { id, qty }[] in features/store/context.tsx |
| Auth cart mirror | GET/POST /api/store/cart | Session-bound; ignores client userId. Guests do not call POST /api/store/cart/hold |
| Checkout quote | GET /api/store/settings + quoteStoreOrder | Shipping prices, promo codes, and product offers. The server recomputes total |
| Checkout | POST /api/store/checkout and placeAndPayStoreOrder | Auth required → StoreOrdersService + inventory reserve + vendorSettlements |
| Pay | POST /api/store/payments/* | PaymentConductor purpose store_order |
| Vendor desk | /vendor/start, /vendor/products | Server actions — not /api/store/vendors |
| Commissions | settlement.ts + /admin/store/commissions | Platform tier % from TIER_BENEFITS (StoreTier) |
Every Entity in your Ring deployment can become a selling vendor — no external marketplace needed. Platform revenue comes from tier-based commission rates on settled sales. Vendors catalogue themselves; operators approve products and settle commissions from the admin cockpit.
Onboard entities at /vendor/start. Trust scoring, tier progression, and suspension live in vendor-lifecycle.
On create/edit product forms: Research → fields + markdown + wiki NODUS + cabinet alt images. Use in gallery is explicit — nothing silently replaces the primary photo.
Tier-based platform commission per sale. Admin dashboard at /admin/store/commissions — dry-run and process due payouts.
Yes — lines live in ring_cart on the device. Signing in hydrates from GET /api/store/cart (server wins) and subsequent edits POST back to the session mirror.
No. Platform commission and referral splits are calculated on vendor order settlement after a payable order exists — not on cart mutations.
No. A product thread appears in Messages only after the shopper writes to the product agent.
Not for non-members. getStoreProducts filters productAudience: 'member' unless the viewer is admin or has member privileges.
Keep ring_cart for guests. For authenticated buyers, treat /api/store/cart as the SSOT on hydrate and after edits; soft-holds may return 409 on insufficient stock. Checkout still requires a session.
POST /api/store/orders still valid?Checkout and orders share the same payable orders pipeline via StoreOrdersService. Prefer the documented checkout entry used by HttpStoreAdapter (/api/store/checkout). Avoid any legacy path that wrote only store_orders — payment webhooks do not settle those.
/admin/store/settings for Nova Poshta and store pickup. /admin/store/promotions for codes and free shipping. A vendor can open both pages; their save does not replace platform-wide codes.
No. quoteStoreOrder recomputes product offers, the promo code, and shipping, then writes that total on the order.
/admin/store/commissions — dry-run due payouts, process due, and hold. Deep dive: Commissions & Settlements.
Call updateTag('store:products') (already wired on product create in app/api/store/products/route.ts). Consumers must go through getCachedProductCatalog().
After order create, UI posts to /api/store/payments/{wayforpay|stripe|credit|token|paypal|card} → PaymentConductor purpose store_order. See PaymentConductor and Store API.
See-also: advertise products in the page curtain and pay authors a commission.
Depends-on: store_order checkouts settle through PaymentConductor and the payment_transactions ledger.
Same-workflow: clone payment rails and env gates that store checkout methods respect.
Next-step: ERP hub for stock invariant, commitSale, and settlements cockpit.
Ring Platform ships a multi-vendor marketplace: any verified Entity can onboard as a vendor, list products, and earn after paid orders settle. Buyers browse a cached catalog, hold a cart, then check out through authenticated order + PaymentConductor rails. Vendors enrich catalog copy with Agent Knowledge Research (WebConductor → fields, markdown, Admin Wiki NODUS, File Cabinet alt images) and opt media into the gallery explicitly.
Use the Founder / Developer tabs in the docs sidebar to filter this page. Cart and checkout below match features/store + app/api/store/* in Layer1 — do not invent extra cart REST beyond the verified session mirror.
| Concern | Where it lives | Notes |
|---|---|---|
| Catalog SSOT | getCachedProductCatalog() → GET /api/store/products | 'use cache' + cacheTag('store:products'); invalidate with updateTag after create |
| Guest cart | localStorage key ring_cart | { id, qty }[] in features/store/context.tsx |
| Auth cart mirror | GET/POST /api/store/cart | Session-bound; ignores client userId. Guests do not call POST /api/store/cart/hold |
| Checkout quote | GET /api/store/settings + quoteStoreOrder | Shipping prices, promo codes, and product offers. The server recomputes total |
| Checkout | POST /api/store/checkout and placeAndPayStoreOrder | Auth required → StoreOrdersService + inventory reserve + vendorSettlements |
| Pay | POST /api/store/payments/* | PaymentConductor purpose store_order |
| Vendor desk | /vendor/start, /vendor/products | Server actions — not /api/store/vendors |
| Commissions | settlement.ts + /admin/store/commissions | Platform tier % from TIER_BENEFITS (StoreTier) |
Every Entity in your Ring deployment can become a selling vendor — no external marketplace needed. Platform revenue comes from tier-based commission rates on settled sales. Vendors catalogue themselves; operators approve products and settle commissions from the admin cockpit.
Onboard entities at /vendor/start. Trust scoring, tier progression, and suspension live in vendor-lifecycle.
On create/edit product forms: Research → fields + markdown + wiki NODUS + cabinet alt images. Use in gallery is explicit — nothing silently replaces the primary photo.
Tier-based platform commission per sale. Admin dashboard at /admin/store/commissions — dry-run and process due payouts.
Yes — lines live in ring_cart on the device. Signing in hydrates from GET /api/store/cart (server wins) and subsequent edits POST back to the session mirror.
No. Platform commission and referral splits are calculated on vendor order settlement after a payable order exists — not on cart mutations.
No. A product thread appears in Messages only after the shopper writes to the product agent.
Not for non-members. getStoreProducts filters productAudience: 'member' unless the viewer is admin or has member privileges.
Keep ring_cart for guests. For authenticated buyers, treat /api/store/cart as the SSOT on hydrate and after edits; soft-holds may return 409 on insufficient stock. Checkout still requires a session.
POST /api/store/orders still valid?Checkout and orders share the same payable orders pipeline via StoreOrdersService. Prefer the documented checkout entry used by HttpStoreAdapter (/api/store/checkout). Avoid any legacy path that wrote only store_orders — payment webhooks do not settle those.
/admin/store/settings for Nova Poshta and store pickup. /admin/store/promotions for codes and free shipping. A vendor can open both pages; their save does not replace platform-wide codes.
No. quoteStoreOrder recomputes product offers, the promo code, and shipping, then writes that total on the order.
/admin/store/commissions — dry-run due payouts, process due, and hold. Deep dive: Commissions & Settlements.
Call updateTag('store:products') (already wired on product create in app/api/store/products/route.ts). Consumers must go through getCachedProductCatalog().
After order create, UI posts to /api/store/payments/{wayforpay|stripe|credit|token|paypal|card} → PaymentConductor purpose store_order. See PaymentConductor and Store API.
See-also: advertise products in the page curtain and pay authors a commission.
Depends-on: store_order checkouts settle through PaymentConductor and the payment_transactions ledger.
Same-workflow: clone payment rails and env gates that store checkout methods respect.
Next-step: ERP hub for stock invariant, commitSale, and settlements cockpit.
Ring Platform ships a multi-vendor marketplace: any verified Entity can onboard as a vendor, list products, and earn after paid orders settle. Buyers browse a cached catalog, hold a cart, then check out through authenticated order + PaymentConductor rails. Vendors enrich catalog copy with Agent Knowledge Research (WebConductor → fields, markdown, Admin Wiki NODUS, File Cabinet alt images) and opt media into the gallery explicitly.
Use the Founder / Developer tabs in the docs sidebar to filter this page. Cart and checkout below match features/store + app/api/store/* in Layer1 — do not invent extra cart REST beyond the verified session mirror.
| Concern | Where it lives | Notes |
|---|---|---|
| Catalog SSOT | getCachedProductCatalog() → GET /api/store/products | 'use cache' + cacheTag('store:products'); invalidate with updateTag after create |
| Guest cart | localStorage key ring_cart | { id, qty }[] in features/store/context.tsx |
| Auth cart mirror | GET/POST /api/store/cart | Session-bound; ignores client userId. Guests do not call POST /api/store/cart/hold |
| Checkout quote | GET /api/store/settings + quoteStoreOrder | Shipping prices, promo codes, and product offers. The server recomputes total |
| Checkout | POST /api/store/checkout and placeAndPayStoreOrder | Auth required → StoreOrdersService + inventory reserve + vendorSettlements |
| Pay | POST /api/store/payments/* | PaymentConductor purpose store_order |
| Vendor desk | /vendor/start, /vendor/products | Server actions — not /api/store/vendors |
| Commissions | settlement.ts + /admin/store/commissions | Platform tier % from TIER_BENEFITS (StoreTier) |
Every Entity in your Ring deployment can become a selling vendor — no external marketplace needed. Platform revenue comes from tier-based commission rates on settled sales. Vendors catalogue themselves; operators approve products and settle commissions from the admin cockpit.
Onboard entities at /vendor/start. Trust scoring, tier progression, and suspension live in vendor-lifecycle.
On create/edit product forms: Research → fields + markdown + wiki NODUS + cabinet alt images. Use in gallery is explicit — nothing silently replaces the primary photo.
Tier-based platform commission per sale. Admin dashboard at /admin/store/commissions — dry-run and process due payouts.
Yes — lines live in ring_cart on the device. Signing in hydrates from GET /api/store/cart (server wins) and subsequent edits POST back to the session mirror.
No. Platform commission and referral splits are calculated on vendor order settlement after a payable order exists — not on cart mutations.
No. A product thread appears in Messages only after the shopper writes to the product agent.
Not for non-members. getStoreProducts filters productAudience: 'member' unless the viewer is admin or has member privileges.
Keep ring_cart for guests. For authenticated buyers, treat /api/store/cart as the SSOT on hydrate and after edits; soft-holds may return 409 on insufficient stock. Checkout still requires a session.
POST /api/store/orders still valid?Checkout and orders share the same payable orders pipeline via StoreOrdersService. Prefer the documented checkout entry used by HttpStoreAdapter (/api/store/checkout). Avoid any legacy path that wrote only store_orders — payment webhooks do not settle those.
/admin/store/settings for Nova Poshta and store pickup. /admin/store/promotions for codes and free shipping. A vendor can open both pages; their save does not replace platform-wide codes.
No. quoteStoreOrder recomputes product offers, the promo code, and shipping, then writes that total on the order.
/admin/store/commissions — dry-run due payouts, process due, and hold. Deep dive: Commissions & Settlements.
Call updateTag('store:products') (already wired on product create in app/api/store/products/route.ts). Consumers must go through getCachedProductCatalog().
After order create, UI posts to /api/store/payments/{wayforpay|stripe|credit|token|paypal|card} → PaymentConductor purpose store_order. See PaymentConductor and Store API.
See-also: advertise products in the page curtain and pay authors a commission.
Depends-on: store_order checkouts settle through PaymentConductor and the payment_transactions ledger.
Same-workflow: clone payment rails and env gates that store checkout methods respect.
Next-step: ERP hub for stock invariant, commitSale, and settlements cockpit.
productAudience: 'member').dagi_research_product returns the same suggested fields / research media / cabinet path for the bound vendor.Storefront product agent chats use Conversation.type: 'product' and stay visible in Messages. Generative Gallery tool chats set metadata kind: 'generative_gallery' (inbox filtering in conversation-service). See Messaging and Generative Gallery.
Settlement platform commission uses StoreTier benefits (constants/store.ts → TIER_BENEFITS):
| Store tier | Platform commission % | Typical settlement cadence |
|---|---|---|
starter | 20% | Weekly |
growth | 17% | Daily |
professional | 15% | Daily |
enterprise | 12% | Instant |
Default fallback when tier benefits are missing: DEFAULT_COMMISSION_PCT = 15. Vendor trust levels (new → premium) track reputation separately from store tier. Referral commission is a dual rail — see Commissions and refcodes.
features/store/services/server-cart.tsCollection store_user_carts; doc id cart_{userId} |
| Cart HTTP | app/api/store/cart/route.ts | Auth required; binds session.user.id only |
| Soft-hold | app/api/store/cart/hold/route.ts | Inventory soft-hold while cart has lines |
| Adapter checkout | features/store/adapters/http-adapter.ts | fetch('/api/store/checkout', { items, info }) |
| Checkout HTTP | app/api/store/checkout/route.ts | Auth → StoreOrdersService + reserveInventoryForOrder; legacy adapter store_orders path is not the payable pipeline |
There is no public unauthenticated cart REST CRUD and no /api/store/vendors apply endpoint. Vendor onboarding is UI + server actions.
features/store/components/checkout/prebilling-page.tsx asks GET /api/shipping/novapost/status whether Nova Poshta is configured (NOVAPOST_API_KEY, read in lib/shipping/nova-post.ts). Branch lookup uses /api/shipping/novapost/cities and /api/shipping/novapost/warehouses.
Prices, ETAs, pickup address, and pickup hours come from platform_settings document store (features/store/services/store-settings-service.ts). Operators edit them at /admin/store/settings. A vendor who opens that page saves a shipping override on vendor_profiles (vendor_<entityId>). A cart that contains only that vendor’s products uses the override. A mixed-vendor cart sums each vendor’s shipping fee (respecting each vendor’s free-shipping threshold against that vendor’s subtotal, falling back to platform rates when a vendor has no override) and records shippingFee on each VendorSettlement.
Express and Standard are not checkout options. A saved preference of express or standard falls back to Nova Poshta or pickup.
| Shipping method | What the form needs | Billing address |
|---|---|---|
nova-post | A selected branch. No street address is required | Forced to the shipping address |
pickup | Name and email. A home address is not required | Pickup address from store settings |
| Other methods when Nova Poshta is off | A saved address, or street and city for a guest | As chosen |
The selected branch card prints the settlement and region as plain text.
| Kind | Where it is stored | Where it applies |
|---|---|---|
| Product offer | store_products.promotions | BOGO, percent off, or amount off on that line |
| Platform promo code | platform_settings / store | Whole cart. Default code WELCOME10 until an admin replaces it |
| Vendor promo code | Same document, with vendorEntityId | Only that vendor’s lines |
Buyers apply a code on the cart. It is kept in localStorage key ring_store_promo. quoteFromSettings in features/store/types/store-settings.ts is the client math. quoteStoreOrder in features/store/services/store-quote.ts is the charge. placeAndPayStoreOrder, POST /api/store/orders, and POST /api/store/checkout ignore the client total.
Codes can have a start date, an end date, maxRedemptions (global cap), and maxUsesPerUser (per-buyer cap verified against paid orders by userId and buyer email). A date-only end date lasts through that UTC day. Online payment rails increment redemptionCount inside fulfillStoreOrderPaid (promoRedemptionCounted: true) so abandoned checkouts do not consume maxRedemptions.
/admin/store/promotions edits codes, free shipping, and the checkout special-offer flag. Platform admins edit platform codes. Vendors edit their own codes and free-shipping policy. Product offers stay on the product form.
Opening a product page no longer creates a Messages thread. GET /api/store/products/<id>/agent-chat only looks up an existing conversation (findExistingConversation). The thread is created when the shopper sends a first message. metadata.buyerEngaged is set after that message is saved, and conversation:new is published then. ConversationService.getConversations hides product threads that are not engaged and have no message from the shopper. A later reply on an old thread backfills the flag.
domains.imageHosts in ring-config.json lists extra hostnames next/image may load from, for example a partner inventory feed. next.config.mjs reads it at build time, so a running image cannot add hosts.| Piece | Path | Role |
|---|---|---|
| Conductor | lib/web/conductor/web-conductor.ts | TextConductor webSearch: true → structured fields + productAgentMarkdown + NODUS JSON + citation-host image candidates |
| Orchestrator | features/store/lib/product-agent-research.ts | Builds request + runProductAgentResearch |
| Cabinet writer | features/store/lib/product-cabinet-media.ts | Dirs store/[storename]/[product-slug]/alt (fits MAX_FOLDER_DEPTH 3; conceptual files/ prefix), SSRF-safe image fetch → RingBase → cabinet nodes |
| Actions | app/_actions/product-agent-research.ts | researchProductAgentAction, researchProductDraftAction, saveProductAgentKnowledgeAction |
| UI | features/store/components/product-agent-knowledge-section.tsx | Create + edit; Use in gallery explicit |
| Wiki helper | features/store/lib/product-nodus-wiki.ts | createProductNodusWikiFromDraft → tenant Admin Wiki |
| DAGI | features/store/services/dagi-erp-tools.ts | dagi_research_product → suggestedFields / researchMedia / cabinetPath / skippedImages |
| Schema notes | AI-LEGIOX/legiox-truth-lens/AGENT-PRODUCT-SCHEMA.md | Photo / research generator steps |
Auth: vendor entity owner or platform admin (resolveResearchVendor + ownership check). Draft research (no product id yet) uses researchProductDraftAction and still writes cabinet artifacts under the vendor owner.
Gallery rule: research media is never auto-merged as primary. Operators must click Use in gallery.
getCachedProductCatalog() in features/store/config.ts ('use cache' + cacheTag('store:products')). Consumers: app/api/store/products/route.ts, getStoreProducts in app/_actions/store-products.ts, MCP app/api/mcp/v1/store/products/route.ts. Invalidate with updateTag('store:products') after create.
| Route | Purpose | Auth |
|---|---|---|
/vendor/start | Vendor onboarding | Subscriber+ |
/vendor/products | Vendor product CRUD + Agent Knowledge | Vendor entity owner |
/admin/store/products | Product approval queue (same form) | Platform admin |
/admin/store/settings | Nova Poshta and pickup prices, ETA, address, hours | Platform admin, or a vendor (saves that vendor’s override) |
/admin/store/promotions | Promo codes, free shipping, checkout special offer | Platform admin, or a vendor (own codes only) |
/admin/store/commissions | Commission settlements | Platform admin |
/admin/store/orders | Order desk | Platform admin |
/admin/store/stock | Stock desk | Platform admin |
/store | Public storefront + audience filter | Public |
/store/settings | Saved addresses and checkout preferences | Signed-in buyer |
Vendor selects a category on the product form.
Adds name+value parameters (“Add product parameter”).
Persists via createProductCustomField() in app/_actions/vendor-actions.ts (ownership-guarded).
Products with productAudience: 'member' (or legacy audience) are hidden unless isAdmin || hasMemberPrivileges(currentRole) in app/_actions/store-products.ts.
features/store/services/settlement.ts reads TIER_BENEFITS[vendor.storeTier || 'starter'].commissionRate (fallback DEFAULT_COMMISSION_PCT). Weighted referral commission uses features/store/lib/referral-commission.ts. Do not document WayForPay’s local getCommissionRateForTier(NEW…PREMIUM) map as the settlement SSOT — that helper is payment-path specific.
| Module | Purpose |
|---|---|
features/store/config.ts | Adapter + cached catalog SSOT |
features/store/context.tsx | Deferred client catalog + cart + checkout call |
features/store/services/server-cart.ts | Authenticated cart mirror |
features/store/services/vendor-lifecycle.ts | Vendor profile + trust levels |
features/store/services/settlement.ts | Commission calculation |
features/store/services/orders-service.ts | Payable orders pipeline |
features/store/services/inventory-sync.ts | reserve / commitSale / cancel restore |
lib/web/conductor/web-conductor.ts | Web product research |
features/store/lib/product-cabinet-media.ts | Research → File Cabinet alt |
app/_actions/product-agent-research.ts | Research / draft / save knowledge |
app/_actions/vendor-actions.ts | Vendor product CRUD + research form fields |
app/_actions/admin-store-erp.ts | Admin product path + Agent Knowledge hidden fields |
features/auth/user-role.ts | hasMemberPrivileges() |
constants/store.ts | StoreTier, VendorTrustLevel, TIER_BENEFITS |
Deep-dive: reserve on checkout → commitSaleForOrder on paid → cancel/refund restore.
productAudience: 'member').dagi_research_product returns the same suggested fields / research media / cabinet path for the bound vendor.Storefront product agent chats use Conversation.type: 'product' and stay visible in Messages. Generative Gallery tool chats set metadata kind: 'generative_gallery' (inbox filtering in conversation-service). See Messaging and Generative Gallery.
Settlement platform commission uses StoreTier benefits (constants/store.ts → TIER_BENEFITS):
| Store tier | Platform commission % | Typical settlement cadence |
|---|---|---|
starter | 20% | Weekly |
growth | 17% | Daily |
professional | 15% | Daily |
enterprise | 12% | Instant |
Default fallback when tier benefits are missing: DEFAULT_COMMISSION_PCT = 15. Vendor trust levels (new → premium) track reputation separately from store tier. Referral commission is a dual rail — see Commissions and refcodes.
features/store/services/server-cart.tsCollection store_user_carts; doc id cart_{userId} |
| Cart HTTP | app/api/store/cart/route.ts | Auth required; binds session.user.id only |
| Soft-hold | app/api/store/cart/hold/route.ts | Inventory soft-hold while cart has lines |
| Adapter checkout | features/store/adapters/http-adapter.ts | fetch('/api/store/checkout', { items, info }) |
| Checkout HTTP | app/api/store/checkout/route.ts | Auth → StoreOrdersService + reserveInventoryForOrder; legacy adapter store_orders path is not the payable pipeline |
There is no public unauthenticated cart REST CRUD and no /api/store/vendors apply endpoint. Vendor onboarding is UI + server actions.
features/store/components/checkout/prebilling-page.tsx asks GET /api/shipping/novapost/status whether Nova Poshta is configured (NOVAPOST_API_KEY, read in lib/shipping/nova-post.ts). Branch lookup uses /api/shipping/novapost/cities and /api/shipping/novapost/warehouses.
Prices, ETAs, pickup address, and pickup hours come from platform_settings document store (features/store/services/store-settings-service.ts). Operators edit them at /admin/store/settings. A vendor who opens that page saves a shipping override on vendor_profiles (vendor_<entityId>). A cart that contains only that vendor’s products uses the override. A mixed-vendor cart sums each vendor’s shipping fee (respecting each vendor’s free-shipping threshold against that vendor’s subtotal, falling back to platform rates when a vendor has no override) and records shippingFee on each VendorSettlement.
Express and Standard are not checkout options. A saved preference of express or standard falls back to Nova Poshta or pickup.
| Shipping method | What the form needs | Billing address |
|---|---|---|
nova-post | A selected branch. No street address is required | Forced to the shipping address |
pickup | Name and email. A home address is not required | Pickup address from store settings |
| Other methods when Nova Poshta is off | A saved address, or street and city for a guest | As chosen |
The selected branch card prints the settlement and region as plain text.
| Kind | Where it is stored | Where it applies |
|---|---|---|
| Product offer | store_products.promotions | BOGO, percent off, or amount off on that line |
| Platform promo code | platform_settings / store | Whole cart. Default code WELCOME10 until an admin replaces it |
| Vendor promo code | Same document, with vendorEntityId | Only that vendor’s lines |
Buyers apply a code on the cart. It is kept in localStorage key ring_store_promo. quoteFromSettings in features/store/types/store-settings.ts is the client math. quoteStoreOrder in features/store/services/store-quote.ts is the charge. placeAndPayStoreOrder, POST /api/store/orders, and POST /api/store/checkout ignore the client total.
Codes can have a start date, an end date, maxRedemptions (global cap), and maxUsesPerUser (per-buyer cap verified against paid orders by userId and buyer email). A date-only end date lasts through that UTC day. Online payment rails increment redemptionCount inside fulfillStoreOrderPaid (promoRedemptionCounted: true) so abandoned checkouts do not consume maxRedemptions.
/admin/store/promotions edits codes, free shipping, and the checkout special-offer flag. Platform admins edit platform codes. Vendors edit their own codes and free-shipping policy. Product offers stay on the product form.
Opening a product page no longer creates a Messages thread. GET /api/store/products/<id>/agent-chat only looks up an existing conversation (findExistingConversation). The thread is created when the shopper sends a first message. metadata.buyerEngaged is set after that message is saved, and conversation:new is published then. ConversationService.getConversations hides product threads that are not engaged and have no message from the shopper. A later reply on an old thread backfills the flag.
domains.imageHosts in ring-config.json lists extra hostnames next/image may load from, for example a partner inventory feed. next.config.mjs reads it at build time, so a running image cannot add hosts.| Piece | Path | Role |
|---|---|---|
| Conductor | lib/web/conductor/web-conductor.ts | TextConductor webSearch: true → structured fields + productAgentMarkdown + NODUS JSON + citation-host image candidates |
| Orchestrator | features/store/lib/product-agent-research.ts | Builds request + runProductAgentResearch |
| Cabinet writer | features/store/lib/product-cabinet-media.ts | Dirs store/[storename]/[product-slug]/alt (fits MAX_FOLDER_DEPTH 3; conceptual files/ prefix), SSRF-safe image fetch → RingBase → cabinet nodes |
| Actions | app/_actions/product-agent-research.ts | researchProductAgentAction, researchProductDraftAction, saveProductAgentKnowledgeAction |
| UI | features/store/components/product-agent-knowledge-section.tsx | Create + edit; Use in gallery explicit |
| Wiki helper | features/store/lib/product-nodus-wiki.ts | createProductNodusWikiFromDraft → tenant Admin Wiki |
| DAGI | features/store/services/dagi-erp-tools.ts | dagi_research_product → suggestedFields / researchMedia / cabinetPath / skippedImages |
| Schema notes | AI-LEGIOX/legiox-truth-lens/AGENT-PRODUCT-SCHEMA.md | Photo / research generator steps |
Auth: vendor entity owner or platform admin (resolveResearchVendor + ownership check). Draft research (no product id yet) uses researchProductDraftAction and still writes cabinet artifacts under the vendor owner.
Gallery rule: research media is never auto-merged as primary. Operators must click Use in gallery.
getCachedProductCatalog() in features/store/config.ts ('use cache' + cacheTag('store:products')). Consumers: app/api/store/products/route.ts, getStoreProducts in app/_actions/store-products.ts, MCP app/api/mcp/v1/store/products/route.ts. Invalidate with updateTag('store:products') after create.
| Route | Purpose | Auth |
|---|---|---|
/vendor/start | Vendor onboarding | Subscriber+ |
/vendor/products | Vendor product CRUD + Agent Knowledge | Vendor entity owner |
/admin/store/products | Product approval queue (same form) | Platform admin |
/admin/store/settings | Nova Poshta and pickup prices, ETA, address, hours | Platform admin, or a vendor (saves that vendor’s override) |
/admin/store/promotions | Promo codes, free shipping, checkout special offer | Platform admin, or a vendor (own codes only) |
/admin/store/commissions | Commission settlements | Platform admin |
/admin/store/orders | Order desk | Platform admin |
/admin/store/stock | Stock desk | Platform admin |
/store | Public storefront + audience filter | Public |
/store/settings | Saved addresses and checkout preferences | Signed-in buyer |
Vendor selects a category on the product form.
Adds name+value parameters (“Add product parameter”).
Persists via createProductCustomField() in app/_actions/vendor-actions.ts (ownership-guarded).
Products with productAudience: 'member' (or legacy audience) are hidden unless isAdmin || hasMemberPrivileges(currentRole) in app/_actions/store-products.ts.
features/store/services/settlement.ts reads TIER_BENEFITS[vendor.storeTier || 'starter'].commissionRate (fallback DEFAULT_COMMISSION_PCT). Weighted referral commission uses features/store/lib/referral-commission.ts. Do not document WayForPay’s local getCommissionRateForTier(NEW…PREMIUM) map as the settlement SSOT — that helper is payment-path specific.
| Module | Purpose |
|---|---|
features/store/config.ts | Adapter + cached catalog SSOT |
features/store/context.tsx | Deferred client catalog + cart + checkout call |
features/store/services/server-cart.ts | Authenticated cart mirror |
features/store/services/vendor-lifecycle.ts | Vendor profile + trust levels |
features/store/services/settlement.ts | Commission calculation |
features/store/services/orders-service.ts | Payable orders pipeline |
features/store/services/inventory-sync.ts | reserve / commitSale / cancel restore |
lib/web/conductor/web-conductor.ts | Web product research |
features/store/lib/product-cabinet-media.ts | Research → File Cabinet alt |
app/_actions/product-agent-research.ts | Research / draft / save knowledge |
app/_actions/vendor-actions.ts | Vendor product CRUD + research form fields |
app/_actions/admin-store-erp.ts | Admin product path + Agent Knowledge hidden fields |
features/auth/user-role.ts | hasMemberPrivileges() |
constants/store.ts | StoreTier, VendorTrustLevel, TIER_BENEFITS |
Deep-dive: reserve on checkout → commitSaleForOrder on paid → cancel/refund restore.
productAudience: 'member').dagi_research_product returns the same suggested fields / research media / cabinet path for the bound vendor.Storefront product agent chats use Conversation.type: 'product' and stay visible in Messages. Generative Gallery tool chats set metadata kind: 'generative_gallery' (inbox filtering in conversation-service). See Messaging and Generative Gallery.
Settlement platform commission uses StoreTier benefits (constants/store.ts → TIER_BENEFITS):
| Store tier | Platform commission % | Typical settlement cadence |
|---|---|---|
starter | 20% | Weekly |
growth | 17% | Daily |
professional | 15% | Daily |
enterprise | 12% | Instant |
Default fallback when tier benefits are missing: DEFAULT_COMMISSION_PCT = 15. Vendor trust levels (new → premium) track reputation separately from store tier. Referral commission is a dual rail — see Commissions and refcodes.
features/store/services/server-cart.tsCollection store_user_carts; doc id cart_{userId} |
| Cart HTTP | app/api/store/cart/route.ts | Auth required; binds session.user.id only |
| Soft-hold | app/api/store/cart/hold/route.ts | Inventory soft-hold while cart has lines |
| Adapter checkout | features/store/adapters/http-adapter.ts | fetch('/api/store/checkout', { items, info }) |
| Checkout HTTP | app/api/store/checkout/route.ts | Auth → StoreOrdersService + reserveInventoryForOrder; legacy adapter store_orders path is not the payable pipeline |
There is no public unauthenticated cart REST CRUD and no /api/store/vendors apply endpoint. Vendor onboarding is UI + server actions.
features/store/components/checkout/prebilling-page.tsx asks GET /api/shipping/novapost/status whether Nova Poshta is configured (NOVAPOST_API_KEY, read in lib/shipping/nova-post.ts). Branch lookup uses /api/shipping/novapost/cities and /api/shipping/novapost/warehouses.
Prices, ETAs, pickup address, and pickup hours come from platform_settings document store (features/store/services/store-settings-service.ts). Operators edit them at /admin/store/settings. A vendor who opens that page saves a shipping override on vendor_profiles (vendor_<entityId>). A cart that contains only that vendor’s products uses the override. A mixed-vendor cart sums each vendor’s shipping fee (respecting each vendor’s free-shipping threshold against that vendor’s subtotal, falling back to platform rates when a vendor has no override) and records shippingFee on each VendorSettlement.
Express and Standard are not checkout options. A saved preference of express or standard falls back to Nova Poshta or pickup.
| Shipping method | What the form needs | Billing address |
|---|---|---|
nova-post | A selected branch. No street address is required | Forced to the shipping address |
pickup | Name and email. A home address is not required | Pickup address from store settings |
| Other methods when Nova Poshta is off | A saved address, or street and city for a guest | As chosen |
The selected branch card prints the settlement and region as plain text.
| Kind | Where it is stored | Where it applies |
|---|---|---|
| Product offer | store_products.promotions | BOGO, percent off, or amount off on that line |
| Platform promo code | platform_settings / store | Whole cart. Default code WELCOME10 until an admin replaces it |
| Vendor promo code | Same document, with vendorEntityId | Only that vendor’s lines |
Buyers apply a code on the cart. It is kept in localStorage key ring_store_promo. quoteFromSettings in features/store/types/store-settings.ts is the client math. quoteStoreOrder in features/store/services/store-quote.ts is the charge. placeAndPayStoreOrder, POST /api/store/orders, and POST /api/store/checkout ignore the client total.
Codes can have a start date, an end date, maxRedemptions (global cap), and maxUsesPerUser (per-buyer cap verified against paid orders by userId and buyer email). A date-only end date lasts through that UTC day. Online payment rails increment redemptionCount inside fulfillStoreOrderPaid (promoRedemptionCounted: true) so abandoned checkouts do not consume maxRedemptions.
/admin/store/promotions edits codes, free shipping, and the checkout special-offer flag. Platform admins edit platform codes. Vendors edit their own codes and free-shipping policy. Product offers stay on the product form.
Opening a product page no longer creates a Messages thread. GET /api/store/products/<id>/agent-chat only looks up an existing conversation (findExistingConversation). The thread is created when the shopper sends a first message. metadata.buyerEngaged is set after that message is saved, and conversation:new is published then. ConversationService.getConversations hides product threads that are not engaged and have no message from the shopper. A later reply on an old thread backfills the flag.
domains.imageHosts in ring-config.json lists extra hostnames next/image may load from, for example a partner inventory feed. next.config.mjs reads it at build time, so a running image cannot add hosts.| Piece | Path | Role |
|---|---|---|
| Conductor | lib/web/conductor/web-conductor.ts | TextConductor webSearch: true → structured fields + productAgentMarkdown + NODUS JSON + citation-host image candidates |
| Orchestrator | features/store/lib/product-agent-research.ts | Builds request + runProductAgentResearch |
| Cabinet writer | features/store/lib/product-cabinet-media.ts | Dirs store/[storename]/[product-slug]/alt (fits MAX_FOLDER_DEPTH 3; conceptual files/ prefix), SSRF-safe image fetch → RingBase → cabinet nodes |
| Actions | app/_actions/product-agent-research.ts | researchProductAgentAction, researchProductDraftAction, saveProductAgentKnowledgeAction |
| UI | features/store/components/product-agent-knowledge-section.tsx | Create + edit; Use in gallery explicit |
| Wiki helper | features/store/lib/product-nodus-wiki.ts | createProductNodusWikiFromDraft → tenant Admin Wiki |
| DAGI | features/store/services/dagi-erp-tools.ts | dagi_research_product → suggestedFields / researchMedia / cabinetPath / skippedImages |
| Schema notes | AI-LEGIOX/legiox-truth-lens/AGENT-PRODUCT-SCHEMA.md | Photo / research generator steps |
Auth: vendor entity owner or platform admin (resolveResearchVendor + ownership check). Draft research (no product id yet) uses researchProductDraftAction and still writes cabinet artifacts under the vendor owner.
Gallery rule: research media is never auto-merged as primary. Operators must click Use in gallery.
getCachedProductCatalog() in features/store/config.ts ('use cache' + cacheTag('store:products')). Consumers: app/api/store/products/route.ts, getStoreProducts in app/_actions/store-products.ts, MCP app/api/mcp/v1/store/products/route.ts. Invalidate with updateTag('store:products') after create.
| Route | Purpose | Auth |
|---|---|---|
/vendor/start | Vendor onboarding | Subscriber+ |
/vendor/products | Vendor product CRUD + Agent Knowledge | Vendor entity owner |
/admin/store/products | Product approval queue (same form) | Platform admin |
/admin/store/settings | Nova Poshta and pickup prices, ETA, address, hours | Platform admin, or a vendor (saves that vendor’s override) |
/admin/store/promotions | Promo codes, free shipping, checkout special offer | Platform admin, or a vendor (own codes only) |
/admin/store/commissions | Commission settlements | Platform admin |
/admin/store/orders | Order desk | Platform admin |
/admin/store/stock | Stock desk | Platform admin |
/store | Public storefront + audience filter | Public |
/store/settings | Saved addresses and checkout preferences | Signed-in buyer |
Vendor selects a category on the product form.
Adds name+value parameters (“Add product parameter”).
Persists via createProductCustomField() in app/_actions/vendor-actions.ts (ownership-guarded).
Products with productAudience: 'member' (or legacy audience) are hidden unless isAdmin || hasMemberPrivileges(currentRole) in app/_actions/store-products.ts.
features/store/services/settlement.ts reads TIER_BENEFITS[vendor.storeTier || 'starter'].commissionRate (fallback DEFAULT_COMMISSION_PCT). Weighted referral commission uses features/store/lib/referral-commission.ts. Do not document WayForPay’s local getCommissionRateForTier(NEW…PREMIUM) map as the settlement SSOT — that helper is payment-path specific.
| Module | Purpose |
|---|---|
features/store/config.ts | Adapter + cached catalog SSOT |
features/store/context.tsx | Deferred client catalog + cart + checkout call |
features/store/services/server-cart.ts | Authenticated cart mirror |
features/store/services/vendor-lifecycle.ts | Vendor profile + trust levels |
features/store/services/settlement.ts | Commission calculation |
features/store/services/orders-service.ts | Payable orders pipeline |
features/store/services/inventory-sync.ts | reserve / commitSale / cancel restore |
lib/web/conductor/web-conductor.ts | Web product research |
features/store/lib/product-cabinet-media.ts | Research → File Cabinet alt |
app/_actions/product-agent-research.ts | Research / draft / save knowledge |
app/_actions/vendor-actions.ts | Vendor product CRUD + research form fields |
app/_actions/admin-store-erp.ts | Admin product path + Agent Knowledge hidden fields |
features/auth/user-role.ts | hasMemberPrivileges() |
constants/store.ts | StoreTier, VendorTrustLevel, TIER_BENEFITS |
Deep-dive: reserve on checkout → commitSaleForOrder on paid → cancel/refund restore.