Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Record the provider architecture decisions
Damian Legawiec7382a7eba1c0
diff --git a/CLAUDE.md b/CLAUDE.mdindex f9f0c6d5dc..c49f3af4a6 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -24,7 +24,7 @@ Active plans (6.0 target, work pending):- `6.0-fulfillment-and-delivery.md` — Shipment→Fulfillment, ShippingMethod→DeliveryMethod, drop ShippingCategory, FulfillmentProvider strategy, pickup (merchant StockLocation) + pickup_point (third-party PickupPointProvider). **Shipped to 6-0-dev (Waves 2+4+6):** renames + deprecated twins, providers (Manual/Digital/Pickup/PickupPoint), dual-emit events, store pickup discovery endpoints, admin delivery_methods/delivery_zones CRUD + dashboard settings pages, FulfillmentMailer; Wave 7 shipping→delivery data migration remains- `6.0-returns-exchanges-claims.md` — First-class Return, Exchange, Claim models replacing ReturnAuthorization/Reimbursement chain- `6.0-platform-auth.md` — Drop Devise, own auth stack, User→Customer/Staff rename (RefreshToken shipped in 5.4)-- `6.0-tax-provider.md` — Per-Market TaxProvider, replaces TaxRate.adjust + Calculator; TaxRate gets direct country/state FKs (tax decoupled from Zone; Zone model dropped in 6.0 via `6.0-delivery-zones.md`)+- `6.0-tax-provider.md` — Per-Market TaxProvider, replaces TaxRate.adjust + Calculator; TaxRate gets direct country/state FKs (tax decoupled from Zone; Zone model dropped in 6.0 via `6.0-delivery-zones.md`); reference provider: Avalara (decisions.md 2026-07-30)- `6.0-delivery-rate-provider.md` — Per-DeliveryMethod DeliveryRateProvider wrapping Stock::Estimator (calculators stay — 2026-07-27 reversal), `store_id` on ShippingMethod, enriched DeliveryRate (carrier/service/date/metadata); monorepo ships one reference multi-carrier provider (Shippo/EasyPost, pick pending — decisions.md 2026-07-29); method rows stay regional (no cross-market method entity)- `6.0-delivery-zones.md` — Zone → DeliveryZone with postal-code-range/prefix members (country-scoped); owns the full ~183-reference Zone consumer inventory; `Spree::Zone` dropped entirely by end of 6.0 (2026-07-27 — 6.0 is the breaking-change window)- `6.0-rich-text-descriptions.md` — Drop ActionText **entirely** at 6.0 (incl. CustomFields::RichText values + Order/User internal notes; gem dependency removed), store sanitized HTML in text columns, serve `field` + `field_html`, **write via `field_html`** (read/write symmetry). description_html serializer shipped 5.4; sanitizer shipped in **5.6.2** with a permissive-but-safe configurable allowlist + `sanitize_rich_text` step in the 5.5→5.6 upgrade manifest (decisions.md 2026-07-27/28), tightened to the Tiptap set at 6.0diff --git a/docs/plans/6.0-tax-provider.md b/docs/plans/6.0-tax-provider.mdindex 30dfa2aa5d..34226c52b5 100644--- a/docs/plans/6.0-tax-provider.md+++ b/docs/plans/6.0-tax-provider.md@@ -3,6 +3,10 @@**Status:** Draft> **Store binding (2026-07-29):** TaxRate and TaxCategory adopt the every-major-model-carries-a-store_id convention as part of this plan's implementation (`Spree::SingleStoreResource`, backfill task, NOT NULL in 6.1) — same treatment DeliveryMethod/StockLocation/DeliveryZone received on the 6.0 core-rewrite branch.+> **Reference provider (2026-07-30):** the first-party reference tax provider is **Avalara** (enterprise-seller target; AvaTax is the enterprise standard). Ships as the canonical Integration-subclass + stateless-provider pair — `Spree::Integrations::Avalara` holding store credentials, the provider writing TaxLines with `provider_id: 'avalara'`. The built-in `'internal'` engine remains the OSS default. Stripe Tax stays third-party territory and carries the merchant-of-record credential caveat (decisions.md 2026-07-30).++> **Provider registry option (2026-07-30):** `TaxLine.provider_id` stays a plain string registry key (`'internal'`, `'avalara'`) — Medusa's tax lines use the identical field name and semantics (`tp_system` for their built-in engine), so the name is the term of art for the audience 6.0 targets; it is deliberately NOT a table reference, preserving the snapshot property after config changes. When this plan is implemented, consider Medusa's shape for the config side: a minimal registry model per engine (identifier + enabled — no credentials) backing per-market provider selection in the admin, with credentialed connections staying `Spree::Integration`. Tax lines keep stamping the string key regardless.+**Target:** Spree 6.0**Depends on:** Split Adjustments (6.0-split-adjustments.md) for TaxLine model, Channels/Catalogs/B2B (6.0-channels-catalogs-b2b.md) for Company.tax_exempt**Author:** Damian + Claudediff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 5047bbded6..40873862c3 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -665,3 +665,49 @@ TaxCategory** follow inside the tax-provider plan's implementation(noted there). Stock availability (`Stock::Quantifier`) intentionallystays location-global until the 6.1 NOT NULL work — correct forsingle-store installs, revisited with multi-store.+++## 2026-07-30 — Credential homes follow cardinality: Integration for store-level connections, PaymentMethod rows for merchant entities++Provider architecture is three layers: store-owned commerce config rows+(DeliveryMethod, PaymentMethod), stateless registry-keyed provider code+(FulfillmentProvider/DeliveryRateProvider/tax engines — never hold+credentials), and `Spree::Integration` as the per-store credentialed+vendor connection (one row per store+type, `can_connect?`, admin+listing). Where credentials live is decided by cardinality, and the two+domains are deliberately opposite:++- **Delivery/vendor APIs — one connection, many methods.** An EasyPost+ account rates every method; config rows multiply, the connection does+ not. Credentials belong on the Integration singleton; provider gems+ ship an Integration subclass + a stateless provider pair+ (`6.0-delivery-rate-provider.md`).+- **Payments — one credential set per merchant entity, several per+ store.** Two Stripe accounts are two merchants of record (separate+ settlement and liability), selected per market at checkout — exactly+ what PaymentMethod rows model, gated by MarketRule once+ `5.7-payment-method-rules.md` lands. Credentials stay on the method+ row; converging them onto Integration would fight its store+type+ uniqueness and is explicitly NOT planned.++Consequence for tax (`6.0-tax-provider.md`): "one Stripe connection+serves payments and Stripe Tax" only holds single-entity. Under multiple+merchants of record, tax liability follows the charging entity per+market — a Stripe Tax provider must resolve credentials consistently+with the market's selected payment entity, not via a store-singleton+Integration lookup.+++## 2026-07-30 — Reference providers: Stripe (payments), Avalara (tax), EasyPost-or-Shippo (delivery)++One first-party reference implementation per provider seam, each+exercising its layer's canonical shape from the credential-cardinality+entry above: **Stripe** for payments (monorepo move per 2026-07-15 —+credentials on PaymentMethod rows, multi-entity capable), **Avalara**+for tax (the enterprise standard, matching the enterprise-seller target;+Integration subclass for store credentials + stateless provider writing+TaxLines with `provider_id: 'avalara'`; the built-in `'internal'` engine+stays the OSS default), and the **EasyPost-or-Shippo** multi-carrier+gem for delivery rates (pick still pending; Integration + provider+pair). Stripe Tax remains buildable by third parties but is not the+reference — and carries the merchant-of-record caveat recorded above.