English source · 9 min
One shop, composable parts
Run Veyndo as a complete shop, or use a component with a system you already run. A storefront, a register and an agent can all work with the same products and orders. Commerce Core owns the current price, stock and order. The JavaScript SDK gives your interface typed access to the shop and its services. HTTP and MCP are also available to other languages and tools.
Follow a purchase · Try the SDK · Find a component · Check what is live.
Follow a purchase
- Find the right product. A shopper chooses a variant in a storefront or an interactive Product Guide. The interface reads the catalog in the shop's language and sales channel.
- Review the real quote. Checkout uses the buyer's cart, selected shipping and payment method. The shopper sees the current total and delivery estimate before confirming.
- Commit once and follow up. Commerce records the order, stock and event together. Checkout can recover the original receipt if a response is lost. A Flow can then hand work to an app or connector, for example to deliver an invoice by email.

Connected Shop runs outside the native storefront. Its Product Guide is an MCP App. The JavaScript SDK connects its catalog, cart and Checkout. The runnable example uses a simulated payment.
How the components fit together
flowchart TB
UI["Shop · Studio · POS · Agents"]
API["SDK / HTTP / MCP"]
C["Commerce Core"]
Q["Checkout"]
P["Payments"]
E["Order · Stock · Event"]
W["Flows · Apps · Connectors"]
K["Knowledge · Reporting"]
UI --> API
API --> C
API --> Q
Q -->|"Quote and purchase"| C
C <--> P
C --> E
E --> W
E --> K
The purchase commits in Core. Workers process follow-up jobs from committed events. Knowledge and reporting read from sources that can be rebuilt. That keeps the price and inventory authoritative across interfaces and lets teams use the same shop from a native screen, a custom frontend or an agent.
What the agent sees
Studio can compose the normal Orders view with shipping policy from Shop Knowledge. An external host can combine the corresponding Commerce and Knowledge reads through the same SDK layout contract. Walkthrough and runnable example.
Installed apps can place interactive results in both Veyndo conversations. The chat host mediates calls to the app's existing operation. A shopper can review a variant's price and delivery before adding it to the cart. A merchant can review and apply a saved catalogue proposal from the same conversation. App cards in the shop and Studio can appear as their data becomes available, while the assistant prepares its reply. Both conversations can carry an applied filter into an editable follow-up. Commerce checks the current shop context and owns the resulting changes. MCP Apps and OpenUI. Build and connect the Product Guide for a complete example with public care cards, private merchant notes, interactive filters and JavaScript tool discovery from the independently released Apps model.
How one shop works
Commerce owns the catalogue, prices, stock and orders. Checkout coordinates the buyer's session and asks that owner for the current quote and the purchase. Commerce checks current purchasing authority and commits the order, stock allocation and event in one transaction. Company and shop authority tests. The receipt can be read independently of the original purchase request.
Read the catalog from JavaScript
Install the SDK using the hosted quickstart. An external storefront can read the same public catalog as the hosted shop. This example uses the German content of the public Lumen demo.
import { createHostedShop } from '@veyndo/sdk/hosted';
const { catalog } = createHostedShop({
shop: 'lumen-story-lab-15-o-98aa4751fa',
locale: 'de-DE',
});
const [context, navigation, first] = await Promise.all([
catalog.context(), catalog.navigation(), catalog.list({ limit: 1 }),
]);
console.log(context.locale, context.currencies, navigation.elements);
const product = first.elements[0];
if (product) {
const detail = await catalog.detail(product.id, { limit: 1 });
console.log(detail.product.name, detail.currencyContext.code);
}
if (first.nextCursor) {
const next = await catalog.list({ limit: 1, after: first.nextCursor });
console.log(next.elements[0]?.name);
}
Use detail.variantsPagination.nextCursor to continue a variant family.
The selected SKU and visible parent can repeat, so combine pages by product
ID. Keep the same shop, channel, language, currency and filters between pages.
Commerce supplies the displayed price and delivery estimate. Checkout uses
the current quote at purchase.
Hosted SDK quickstart.
Run the browser example
In a Node 22 or newer project, install the SDK and start the included host.
node node_modules/@veyndo/sdk/examples/browser.mjs
Open the printed loopback address. The example loads the public Lumen
catalog. Select Load more products to follow the next page, or search
for Tischleuchte and open the result to see the current price and stock.
The same package contains a command line version at
node_modules/@veyndo/sdk/examples/store-catalog.mjs.
The browser calls its local Node host. The host uses the SDK to read the
configured Store API, so the browser needs no shop credentials or cross
origin access. The host uses Node's standard library and binds to loopback.
Set VEYNDO_URL, VEYNDO_SHOP and VEYNDO_LOCALE before starting it to
use another public catalog.
Example source.
Connect checkout
JavaScript and TypeScript clients can create a draft, submit a reviewed purchase and check the original receipt with the typed Checkout SDK. Prepare and review a cart. Choose shipping and payment. Show the checkout terms and record acceptance. Use the Core relay. Manage the buyer session and password · Manage buyer profiles and addresses · Read orders and download a receipt · Download purchased files.
Core supplies checkout to both the native storefront and Storyfront. In the public Lumen test shop, both browser routes completed a PayPal Sandbox capture through the private Checkout service and returned to an empty cart. Both use the same Commerce owner for quote, commit and receipt. Studio refunded both Sandbox captures. A separate demo order generated an invoice through the app worker. The hosted mail delivery test still needs a sender and transport. Live pilot and verification. Current shared Cart rollout and public demo purchase. Reproduce purchase recovery and compare the isolated Northflank runs.
The original Core and App Worker images also passed native purchase and invoice recovery as separate hosted services with restricted system and tenant database roles. Hosted startup and isolation checks.
Five separately hosted workloads now passed a private Northflank rehearsal. Independent Checkout recovered a demo purchase after a restart. A native purchase exercised the separate Payments simulator, signed callback, app worker, invoice, Connector, SMTP receiver and refund. The two tests shared the same Core with signed database scope. Core owned each order and stock movement. Builds and results.
A paired Northflank run then measured the cost of forwarding confirmations to Checkout while Core served catalogue reads. A bounded wait before forwarding reduced confirmation p95 from 2.99 s to 1.07 s. Both settings produced one order, stock movement, invoice and test mail per purchase. Core kept the same transaction boundary and limits for checkout and its callbacks. Load and recovery evidence.
The storefront and Studio use that same shop identity and transaction boundary. Provider calls run through durable jobs. Knowledge and reporting can be rebuilt from their sources. They add context and visibility without joining the purchase transaction. Agents use the same admitted operations as the team and prepare changes for review where approval is required.
Choose a starting point
For Rust integrations, the Commerce crate guide shows shared product, cart, contact and address contracts. Its contact example runs without a server. The host still owns account identity, PII admission and the atomic order transaction. Independent HTTP/MCP hosting for the remaining Commerce domains is tracked in CORE-02..10.
The four public development repositories are linked below. The other links explain the component's contract and its place in the complete shop. Some have separate builds or access-controlled source, and some are still domains in the product repository. The implementation plan tracks each extraction and the current status records what has been released and tested.
The same release checker prepares a pinned update for any build-backed component while retaining every peer. A presentation update does not move stock, pricing or order ownership into the frontend. Component release procedure.
The machine-readable component catalog lists verified public release tags and their commits, along with the exact source and image versions recorded for the hosted pilot. Each entry links to its guide. The public release and hosted pilot sections track different artifacts, so an SDK or source tag does not imply that the same code is running on Northflank.
| Component | What it owns and where to start |
|---|---|
| Commerce | The complete shop, Studio, checkout transaction, inventory, orders, rights and shared API. Repository · Run it locally |
| SDK | JavaScript and TypeScript clients for Veyndo's HTTP and MCP interfaces, including separately scoped services. Repository · Connected Shop |
| Apps | App manifests, bounded Wasm execution and common storage for records, settings and jobs. Repository · Runtime guide |
| Marketplaces | Provider mapping, listings and imported orders for Amazon, eBay and Kaufland. A compatible commerce host owns inventory and order creation. Repository · Merchant guide |
| Checkout | Buyer review, checkout sessions and recovery of the original result. The commerce host owns prices, stock and the final purchase. Native and Storyfront · External storefront example |
| Policies | Shared pricing, promotion and rule decisions. The native product applies them using current facts. Verification scope |
| Automation | Previews rules from supplied facts over HTTP or MCP. Core links the same pinned rule source in-process and runs Flows from committed orders. External Rust hosts can use the graph validator, Flow catalog and execution directives. Component guide · Worker rollout · Rust contract · Draft check |
| Knowledge | Private documents, a rebuildable catalog projection and verifiable evidence. Import your own catalog or documents with the SDK. Core keeps selling during a Knowledge outage. SDK example · Database recovery · Shop knowledge |
| Catalog AI and agents | Import, enrich and translate catalog data. Agents prepare revision-bound proposals within their grants. Catalog and agent workflows · Agent rights |
| Simulator | Runs isolated shopper scenarios so teams can compare changes before release. Simulator |
| Canvas and Experience | Visual shop editing and the original Storyfront experience use their own presentation. Commerce supplies catalog and checkout operations. Canvas · Storyfront |
| Connectors | Nine provider adapters share encrypted settings, durable delivery and receipts. Run the service with Core or with its own database and scoped HTTP/MCP access. Component guide |
| Migration | Read source shops and hand reviewed imports to the target shop. Migration guide |
| B2B and EDI | Companies, budgets and approvals govern purchasing. EDI normalizes partner documents for the same purchasing workflow. B2B · EDI |
| POS | Cashier workspace and register protocol. Sales and refunds use the host's inventory, order and receipt rules. Register guide |
| Shipping | Package, label, tracking and return contracts for independent carrier apps. Shipping guide |
| Reports | Sales, traffic and channel measures derived from authorized shop data. Reports guide |
| Payments | The provider contract connects account setup, payment attempts, verified callbacks and refunds to the native order. Payment API · Shopware Payments acceptance |
What we check when components work together
The hosted Lumen profile records the exact builds and database inputs of the eight services it connects. Operators can compare the deployed versions, running replicas and configured probe results before a change. This gives a test run a reproducible version set without adding requests to the storefront or checkout. Verify the hosted profile.
Compare the same commerce operation through both entry points under equivalent load. Check the actual quote and receipt as well as latency. In the local Checkout rollback rehearsal, Core placed native and hosted handoff orders while Checkout was stopped and reconciled an existing payment. The recovered receipt kept the original purchase identity.
The benchmarks explain which paths, workloads and environments were measured. Local synthetic results and public reachability checks are reported separately from hosted capacity and provider acceptance.
The hosted shop now runs its app worker separately from Core. The worker owns Flow execution, app scheduling and delivery from the existing queues. The checkout and its original receipt still use the same Commerce owner. Hosted cutover and measurements.