Modules
Sourced from app/src/modules.ts (the composition root’s module registry)
and each module’s own src/index.ts header comment — the published
interface every module exposes. If a module isn’t in this list, it isn’t
mounted and doesn’t run.
| Module | Schema | Purpose |
|---|---|---|
stores | stores | The tenant registry — fail-closed Host -> tenant resolution (ADR 0003), the credential-carries-ownership pattern, and the first real publisher of store.provisioned.v1. |
persons | persons | Tenant-scoped shopper/person registry — identity, email, phone, address book. |
provisioning | provisioning | The tenant-onboarding run engine — idempotent, resumable step execution through other modules’ interfaces, never raw SQL into another module’s schema. |
provenance | provenance | The supplier-side partner/provenance registry behind the Polymer Partner seal — public widget verification, canonical records, merchant partnership reads, and operator registry CRUD. |
entitlements | entitlements | Plan-gating: given a tenant and an opaque subject, resolves the set of features that subject can access. |
flags | flags | Operational kill-switches and rollout toggles. |
identity | identity | Minimal merchant-user auth — magic-link login, session verification, and the WorkOS access-token exchange (backend-verified AuthKit token -> identity session, for portal owner self-mint). Still not a WorkOS/M2M wrapper; the M2M plane was deliberately dropped. |
cash | cash | Store-scoped store-credit / rewards-cash ledger — append-only entries, deterministic idempotency, fail-closed overdraft protection. |
giftcards | giftcards | Purchasable/redeemable gift-card codes — bearer-instrument money (issue mints a hashed code, redeem applies it as tender at checkout), a structural mirror of cash with the same accounting-offset outbox. |
accounting | accounting | The platform-wide, per-tenant immutable double-entry ledger — the source of truth for money. |
affiliates | affiliates | Referral attribution, multi-level commission calculation, and refund reversal. |
webhooks-gateway | webhooks | The universal inbound front door for third-party callbacks — verify, dedup, store, fan out one event. |
inventory | inventory | Lot-tracked physical stock, FEFO reservations, and an append-only movement/adjustment log. |
commerce | commerce | Tenant-scoped product catalog (products/variants, integer-cents prices) and the order lifecycle. Publishes commerce.order.placed.v1. |
fulfillment | fulfillment | The pick/pack/ship loop — one queue row and one shipment per order, allocation against inventory reservations, label purchase. |
comms | comms | Transactional email send core — deterministic-dedup sends, a fail-closed suppression gate, and an explicit opt-out consent gate. |
marketing | marketing | Marketing activation — a durable drip/campaign runner, audience resolution + enrollment, abandoned-cart detection, and bounce ingestion, driving sends through comms in-process. |
media | media | The write side of the media pipeline — mints presigned upload credentials, records tenant-scoped audited asset rows, and confirms/flips them to ready on finalize (behind a vendor-neutral MediaProvider port). |
payments | payments | Vendor-neutral payment-provider port — an injected PaymentProvider, defaulting to a real NMI implementation. |
fraud | fraud | The fraud & abuse floor — an append-only order-attempt log for sliding-window velocity checks, an operator-managed blocklist, and the pure AVS/CVV + velocity decisioning checkout runs before money moves. |
merchant-billing | merchant_billing | B2B invoicing for tenant merchant orgs — effective-dated contracts, usage/cost-fact ingestion, invoice generation, a guarded collection state machine. |
subscriptions | subscriptions | A recurring-billing engine — a billing schedule, a renewal sweep, and a dunning ladder driven off a vaulted merchant-initiated (MIT) credential, charging through the payments provider port. |
checkout | (none — composes commerce + payments) | The seam that makes an order actually purchasable: cart -> priced order -> payment intent -> capture -> placed, or a classified decline. |
beacon | beacon | The ad-events router — batch ingest with fail-closed token to tenant binding, a per-destination dispatch ledger, and the Meta CAPI payload builder. |
outbound-webhooks | outbound_webhooks | Merchant deliveries and federation — the dispatch ledger, retry/DLQ/replay. |
merchant-api | (none — reads three other modules) | The fdk_-key-authenticated public API over orders, catalog, and webhook management. See Tenant-facing API. |
analytics | analytics | Merchant reporting — the platform’s rollup surface over every other module’s data, served over an fdk_ credential (manage:own_analytics) at /v1/merchant/analytics/*, tenant derived from the credential. |
workflow | workflow | A DB-backed durable step executor. Ships with zero production workflow definitions — the first one arrives with its owning feature. |
Key developer-facing routes
Most modules are operator-gated internals with no partner-facing surface. The
ones a merchant or storefront actually calls — with an fdk_ credential, the
x-storefront-token, or no auth at all — are the small set below. Route paths
are shown as the handlers define them; see the linked page for the full
contract, and the machine-generated spec at https://api.ruo.pro/openapi.json
for the public storefront and fdk_ surface.
| Module | Surface | Where |
|---|---|---|
stores | Public GET /v1/tenants/:tenant/site; self-serve /v1/my/store, /v1/my/store/manifest, /v1/my/site*, /v1/my/domains, /v1/my/credentials. | Site builder, Tenant-facing API |
commerce | Public catalog reads /v1/tenants/:tenant/catalog/*. | Tenant-facing API |
checkout | Storefront-token checkout /v1/tenants/:tenant/checkout*; merchant order actions /v1/merchant/orders/:id/{refund,cancel}. | Tenant-facing API |
merchant-api | fdk_ API over orders, catalog, webhooks, and billing reads (/v1/merchant/*). | Tenant-facing API, Merchant billing |
media | Merchant media library /v1/merchant/media/*. | Media |
entitlements | Merchant add-on enable/disable /v1/merchant/entitlements/*. | Add-on marketplace |
merchant-billing | Merchant recoup read /v1/merchant/recoup (invoice/statement reads are served via merchant-api). | Merchant billing |
outbound-webhooks | Signed merchant deliveries + the dispatch ledger (managed via merchant-api). | Webhooks |
Every other module (persons, provisioning, flags, identity, cash,
accounting, affiliates, inventory, fulfillment, comms, payments,
beacon, workflow) is operator-gated or consumed only in-process by the
modules above — none is a partner contract today.
Non-module directories referenced above
edges/webhooks-gateway/andedges/outbound-webhooks/are the two true network boundaries (not modules — see Topology).surfaces/storefront/,surfaces/console/,surfaces/portal/,surfaces/docs/are the entry points that consume the modules above.