Architecture

ProjectR is a three-piece system around one Convex backend and one Shopify store. This section documents the load-bearing flows — read Order to Rewards and Webhook Pipeline first; they are where production incidents have historically lived.

The invariants that shape everythingCopy Anchor Link

1. One Shopify store for all environments. Every deployment that sets SHOPIFY_WRITES_ALLOWED=1 writes to the live store, and the rest refuse Admin API mutations.
2. The type contract — backend schema changes re-type both apps immediately; deploys are not atomic.
3. Rewards basis is the subtotal. Stamp minimum spend is checked after discounts and excludes shipping and tax.
4. Aggregates must be maintained — every insert/patch/delete on a tracked table updates its @convex-dev/aggregate in the same transaction, or dashboard stats silently corrupt.
5. One notification pipeline — every producer funnels through enqueueNotification.