Concepts

This page is the domain model. Every protocol surface in Aly — MCP, UCP, A2A, x402, REST — reads and writes the same entities. Once you know these, the surfaces are largely shape conversions on top.

Workspaces and users

A workspace (sometimes orgIdin the codebase) is the unit of ownership and billing. A workspace contains sites, products, orders, customers, API keys, OAuth clients, and team members. Every API key and OAuth token is bound to exactly one workspace at issuance. Authorization checks run against the workspace; the issuing user's identity is retained for audit only.

Sites

A site is a published storefront — a slug, theme, navigation, set of sections, and configuration for memberships, voice, crypto payments, and domain. Each workspace can own many sites. Sites publish to <slug>.aly.store on a wildcard subdomain or a custom domain.

A site is either draft or published. Publishing triggers ISR revalidation of the public storefront URL.

Products and variants

A product belongs to a site. It has a name, base price, description, media, optional digital file, and zero or more variants. Variants override price and stock per option combination (size, color, format).

Digital products carry a downloadable file reference. Physical products carry shipping configuration. A product can be both — for example, a print plus a downloadable companion guide.

Collections

A collection groups products for navigation or merchandising. Collections are either manual (explicit product list) or rule-based (filters on tags, price, stock).

Carts and orders

A cart is a checkout session in flight — it has a token, line items, shipping address, optional coupon, and computed totals (subtotal, shipping, tax, discount, total). Carts move from active to abandoned or completed.

An order is the post-payment record. It carries the line items, buyer, shipping/billing addresses, payment metadata, and an evolving fulfillment state machine — pending, fulfilled, returned, exchanged, refunded.

Customers and customer groups

A customer is a buyer profile — email, name, addresses, order history, optional membership. Customers are bound to a site (not a workspace) so a single email can be a customer on multiple sites with different histories.

Customer groups are segments — VIP, wholesale, free tier — used for price list eligibility, coupon targeting, and membership tiers.

Coupons and price lists

Coupons are discount codes — percentage or fixed, usage cap, date range, optional product/collection scope, optional customer-group eligibility.

Price lists are dynamic pricing rules — a customer group plus an override (percentage off, fixed price, free shipping). Useful for wholesale, member discounts, and ad-hoc segments.

Memberships

A membership is a recurring subscription tier attached to a site — title, price, billing interval, perks. Buyers become members through Stripe Subscriptions. Membership state gates product visibility, price list eligibility, and gated content blocks.

Voice agents

Sites can opt into a voice section — a buyer can talk to an agent about products, ask follow-ups, and check out by voice. Voice is powered by ElevenLabs and LiveKit and is configured per-site (system prompt, voice id, allowed skills).

Agent tasks (A2A)

An A2A task is a multi-turn agent interaction persisted in Convex. Tasks have a context_id (the conversation), a status (working, completed, cancelled, failed), an append-only message log, and zero or more artifacts attached when a skill executes successfully (e.g. an order id, a quote).

Webhooks

A webhook endpoint is a URL plus an event subscription list, owned by a workspace. Aly POSTs HMAC-signed event payloads asynchronously, retrying with exponential backoff. Every delivery is logged with timestamp, status code, and response body for audit.

OAuth clients

An OAuth client is a registered third-party agent application. Clients are created via dynamic registration; each gets a client_id, a client_secret, and the ability to walk users through the consent flow to mint aly_oauth_* access tokens scoped to the consenting workspace.

Media

Binary assets — product images, site media, downloadable digital files — are stored in Cloudflare R2 buckets. Public assets are served via cdn.aly.store with optional Cloudflare Images transforms; private digital files are served through signed, short-lived URLs created at order completion.

Mental model

If you remember one thing: each surface (MCP tool call, UCP checkout session, REST mutation) is a thin auth + validation layer over the same Convex mutations the dashboard editor uses. There is no parallel agent-only data plane — agents see the same rows the editor does, and their writes are equally durable.