Loading documentation...
Preparing Ring Platform content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring Platform content
Preparing Ring Platform content
Preparing Ring Platform 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; soft-holds via POST /api/store/cart/hold |
| Checkout | POST /api/store/checkout | Auth required → StoreOrdersService + inventory reserve |
| 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.
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/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.
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.
Deep-dive: reserve on checkout → commitSaleForOrder on paid → cancel/refund restore.
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; soft-holds via POST /api/store/cart/hold |
| Checkout | POST /api/store/checkout | Auth required → StoreOrdersService + inventory reserve |
| 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.
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/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.
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.
Deep-dive: reserve on checkout → commitSaleForOrder on paid → cancel/refund restore.
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; soft-holds via POST /api/store/cart/hold |
| Checkout | POST /api/store/checkout | Auth required → StoreOrdersService + inventory reserve |
| 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.
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/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.
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.
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.
| 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/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 |
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 |
Next-step: vendor commission ledger, dry-run payouts, and referral dual-rail.
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.
| 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/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 |
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 |
Next-step: vendor commission ledger, dry-run payouts, and referral dual-rail.
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.
| 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/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 |
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 |
Next-step: vendor commission ledger, dry-run payouts, and referral dual-rail.