ShopCo Sample SaaS

Full pipeline YAML demo — multi-stage onboarding with profile memory and tool gating.

The ShopCo sample (examples/sample-saas in the Aelio-Convox repo) is the reference integration for YAML-backed conversational pipelines.

For a step-by-step guide on creating your own YAML file and linking it in your project, see Pipeline YAML Manifest — Part 1 (create) and Part 2 (link).

What it demonstrates

Feature	Implementation
YAML pipeline manifest	`manifests/shopco.pipeline.yaml`
Manifest loader	`src/load-manifest.ts`
Backend tools	`src/index.ts` via `aelio.expose()`
In-memory business data	Orders, subscription, invoices `Map`
REST API	Parallel `/api/*` routes
Multi-stage onboarding	`unverified → verified → onboarding → active`
Tool gating	`tool_groups` block writes during onboarding
Profile memory	Email, name, shopping preference
Widget quick replies	`intent_ack`, `shopping_preference` chips

Run the demo

From the Aelio-Convox repo root:

pnpm install
pnpm build
pnpm start

URL	Purpose
http://localhost:3010/demo.html	Pipeline demo page with widget
http://localhost:3010/ready	Server readiness + pipeline registration
http://localhost:8081/health	ShopCo backend health

Click New user on the demo page to start a fresh pipeline for a unique customer id.

Project layout

examples/sample-saas/
├── manifests/
│   └── shopco.pipeline.yaml    # Declarative pipeline config
├── src/
│   ├── load-manifest.ts        # YAML → aelio.pipeline/attribute/flow
│   └── index.ts                # REST API + aelio.expose() tools
└── package.json

Boot sequence

import { loadShopCoManifest } from './load-manifest.js';

// 1. Load YAML manifest (stages, attributes, flows, policies)
loadShopCoManifest();

// 2. Register tools (referenced by flow steps in YAML)
aelio.expose('listOrders', async ({ status }, ctx) => { /* ... */ }, {
  description: "List the customer's orders",
  params: { status: { type: 'string', optional: true } },
  safety: 'read',
  intent: 'order_inquiry',
});

// 3. Connect to Aelio server
await aelio.listen({
  secret: process.env.AELIO_SDK_SECRET,
  url: process.env.AELIO_SERVER_URL ?? 'ws://127.0.0.1:3010',
});

Every new customerId starts at pipeline stage unverified. Stage and flow progress are stored by Aelio in SQLite — not in ShopCo's in-memory Map.

Exposed tools

Tool	Safety	Intent	Used in flow
`syncProfile`	read	onboarding	`shopco_onboarding.sync_profile`
`listOrders`	read	order_inquiry	`shopco_onboarding.review_orders`
`getSubscription`	read	subscription	`shopco_onboarding.check_plan`
`listInvoices`	read	billing	`shopco_onboarding.view_invoices`
`getOrderStatus`	read	order_inquiry	Active stage (free chat)
`cancelOrder`	write	cancellation	Active stage only
`upgradePlan`	write	subscription	Active stage only

Write tools are blocked during onboarding via:

onboarding:
  blocked_groups: [writes]

Walking through the pipeline

Unverified — Assistant delivers the ShopCo pitch. Tap Let's go (quick reply) or say yes. Flow: welcome.

Verified — Provide an email (e.g. you@example.com). Flow: verify_identity.

Onboarding — Name → preference chips → profile sync → orders → plan → invoices. Flow: shopco_onboarding.

Active — Full support. Try cancel order A-1002 or upgrade me to pro.

Adapting for your product

Copy manifests/shopco.pipeline.yaml → manifests/your-product.pipeline.yaml
Copy src/load-manifest.ts and rename types/helpers for your schema
Update stages, attributes, and flows for your onboarding
Implement tools in index.ts — reference them from YAML tool: fields
Align tool intent values with your tool_groups intent lists

Attributes vs your database

Attribute values (email, name, preference) are stored in Aelio's profile memory (customer_attributes). Your tools should read business data from your own database. The sample's syncProfile tool is a checkpoint in the tour — it does not write back to the in-memory ShopCo Map.

Verify registration

curl -s http://127.0.0.1:3010/ready | jq '{
  pipeline: .sdk.pipeline != null,
  flows: .sdk.flows,
  attributes: .sdk.attributes
}'

Pipeline YAML Manifest — full YAML reference
Express integration — minimal tool-only setup
Local Development — run the full stack

On this page