Commerce Architecture & Specs
An event-driven, schema-first commerce engine designed for strict ACID compliance, atomic inventory locking, real-time fraud detection, and offline-capable POS.
Performance & Commerce Metrics
P50 Checkout Latency
12ms
P95 Checkout Latency
42ms
API Throughput
10,000 req/sec (Horizontally Scalable)
Offline POS Sync
idempotency-keyed order replay on reconnect (server-side dedup) + a compiled pricing engine deployed to a connected Bridge POS register for local on-device pricing
Fraud Detection Latency
<5ms per order
Inventory Lock Timeout
5 seconds (prevents deadlocks)
Recovery Email Sequence
3-step (1h, 24h, 72h) with token-based URLs
1. Schema-Driven Architecture
Every commerce entity (products, orders, customers, subscriptions, gift cards) is a strictly typed collection backed by PostgreSQL 17.
Auto-Generated APIs: The platform's dynamic routing exposes REST endpoints providing 30+ filter operators, cursor/offset pagination, and sparse fieldsets out of the box.
Infinite Extensibility: Core structured fields map to indexed SQL columns for lightning-fast querying, while dynamic attributes (like custom product specs) map to flexible JSON fields, allowing schema flexibility without requiring costly database migrations.
Multi-Location Inventory: Inventory is tracked per-location with available, reserved, and committed quantities. Location-aware availability checks run during checkout.
2. Atomic Inventory Locking
Order processing relies on strict row-level database locking to ensure inventory counts are decremented atomically, eliminating double-sell race conditions during flash sales.
The Reserve Flow: 1. Stock is verified for each item (global or per-location) 2. A row-level lock is acquired on the affected product rows 3. A 5-second lock timeout prevents deadlock accumulation under high concurrency 4. On success, the reserved quantity increments; on failure, rollback releases all locks
Deduplication: Reservations are keyed to the order, so duplicate reservation calls for the same order return the existing reservation without re-reserving.
Release on Cancellation: Order cancellations return reserved stock to the available pool automatically, under the same locking guarantee.
3. Real-Time Fraud Detection
| Signal | Weight | Description |
|---|---|---|
| IP Velocity (high) | +40 | 6+ orders from the same IP in the last 24h |
| IP Velocity (elevated) | +20 | 3-5 orders from the same IP in the last 24h |
| Email Velocity | +20 | 4+ orders from the same email in the last 24h |
| High-Value Order | +30 | Order ≥ $3,000 |
| Elevated-Value Order | +20 | Order ≥ $1,000 |
| Moderate-Value Order | +10 | Order ≥ $500 |
| Disposable Email | +30 | Email domain in a 56-entry disposable-domain list |
| Billing Mismatch | +25 | Billing ZIP and state both differ from shipping |
| First Order + High Value | +15 | No prior orders from this email, and order > $200 |
4. Abandoned Cart AI Recovery
| Step | Delay | Subject Pattern | Content |
|---|---|---|---|
| Reminder | 1 hour | "You left items in your cart" | Product list + direct checkout link |
| Discount | 24 hours | "Complete your order with X% off" | Generated discount code + urgency |
| Final | 72 hours | "Your cart is about to expire" | Last chance + expiration countdown |
5. Subscription Renewal Engine
Recurring billing uses status-based locking to prevent double-renewal under concurrent processing.
Status Lifecycle: active → renewing → active (success) or past_due (failure)
Concurrency Protection: The renewal process uses optimistic locking:
1. Status set to renewing
2. Verified that this attempt won the lock
3. Payment processed and order created
4. On failure, status is marked past_due and a payment-failed event is emitted
Dunning Events: Failed renewals emit a payment-failed event carrying subscription, customer, plan, and failure reason for downstream recovery workflows.
6. Native POS Hardware Integration
| Device | Protocol | Features |
|---|---|---|
| Receipt Printer | ESC/POS over USB/Serial | Line items, QR codes, store branding |
| Cash Drawer | Printer DCD pin or serial | Kick-open via print job |
| Card Reader | USB HID mag-stripe/chip | Masked card number only (PCI compliance) |
| Barcode Scanner | USB HID keyboard wedge | Real-time product lookup |
| Customer Display | USB/Serial | Running totals, item names |
| Label Printer | ESC/POS thermal | Price tags, shelf labels |
typescript
// Example: create an order via the Commerce APIconst res = await fetch("/api/v1/commerce/checkout", { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` }, body: JSON.stringify({ cartId, paymentMethodId, // tokenized payment method from your gateway's SDK }),});
if (!res.ok) { const { errors } = await res.json(); throw new Error(errors[0].message); // e.g. "Order flagged by fraud detection"}
const { data: order } = await res.json();
// Example: print a POS receipt via Bridgeawait fetch("/api/v1/commerce/bridge/receipt/print", { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` }, body: JSON.stringify({ storeName: "Downtown Store", orderNumber: order.orderNumber, items: order.items, subtotal: order.subtotal, tax: order.tax, total: order.total, paymentMethod: "Visa **** 4242", }),});These are planned integrations with Aeion Spatial, not yet shipped in Commerce. The intended design: a video editor that tracks moving products across frames so customers can add-to-cart directly from marketing video, and for 3D products, a visual node-based material builder that compiles into a ready-to-render 3D component for AR shopping. The underlying compilation engine ships today (used elsewhere in the platform); the shoppable-hotspot editor and the 3D-configurator generator for Commerce specifically are on the roadmap.
B2B portals use dedicated wholesale price lists keyed by customer tier and minimum quantity thresholds. Order routing evaluates these rules at checkout, applying tier-specific pricing and payment terms (net-15, net-30, net-60). Multi-tier approval workflows route large orders through configurable approval chains before fulfillment.
Smart order routing evaluates available inventory locations against shipping cost and delivery time tradeoffs. It considers: real-time stock levels, customer location, warehouse proximity, carrier rates, and fulfillment cost. Routing decisions optimize for either cost (cheapest warehouse) or speed (fastest delivery) based on cart configuration.