Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Record the provider architecture decisions

Damian Legawiec7382a7eba1c0
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.0
diff --git a/docs/plans/6.0-tax-provider.md b/docs/plans/6.0-tax-provider.md
index 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 + Claude
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 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`) intentionally
stays location-global until the 6.1 NOT NULL work — correct for
single-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.