@spree/docs 0.1.182 → 0.1.184

package/dist/developer/core-concepts/architecture.md

@@ -1,176 +1,147 @@
 ---
 title: Architecture
-description: Explore how Spree's core models, APIs, and gems fit together — catalog, shopping, checkout, fulfillment, and pricing — for headless or embedded commerce.
+description: How Spree fits together — the catalog, the cart, the order, and fulfillment — and the two APIs you build against.
 ---
 
 ## Overview
 
-Spree is a commerce engine built around interconnected models that represent the core concepts of commerce: products, orders, payments, and shipments. It adapts to your stack — use it as a headless API for any frontend, embed it into an existing application, or scale it from a single storefront to a global multi-vendor marketplace.
+Spree is a commerce engine you drive through a REST API. It holds the catalog, works out what a customer owes, takes the money, and tracks what was sent. You build the storefront, the mobile app, or the internal tool on top of it.
 
-> **INFO:** Spree supports PostgreSQL, MySQL, and SQLite. PostgreSQL is recommended for production. [Learn more about database configuration](../deployment/database.md).
+There is no built-in storefront you have to accept. Everything a customer-facing app needs is on the Store API, and everything a back office needs is on the Admin API. Both ship as typed TypeScript clients.
 
-## Core Commerce Flow
+## The shape of a purchase
 
-The following diagram shows how the main models interact during a typical customer purchase:
+Four things carry a purchase from browsing to delivery. Each one has a job the others don't:
 
-```mermaid
-flowchart TB
-    subgraph Catalog["Catalog"]
-        Product --> Variant
-        Variant --> Price
-        Variant --> StockItem
-        StockItem --> StockLocation
-    end
-
-    subgraph Shopping["Shopping"]
-        User --> Order
-        Order --> LineItem
-        LineItem --> Variant
-    end
-
-    subgraph Checkout["Checkout"]
-        Order --> Address
-        Order --> Shipment
-        Order --> Payment
-        Shipment --> ShippingMethod
-        Payment --> PaymentMethod
-    end
-
-    subgraph Fulfillment["Fulfillment"]
-        Shipment --> InventoryUnit
-        InventoryUnit --> Variant
-        StockLocation --> Shipment
-    end
-
-    subgraph Pricing["Pricing & Adjustments"]
-        Order --> Adjustment
-        LineItem --> Adjustment
-        Shipment --> Adjustment
-        TaxRate --> Adjustment
-        Promotion --> Adjustment
-    end
-```
-
-**How it works:**
 
-1. **Catalog** — [Products](products.md) have [Variants](products.md#variants) (SKUs) with prices and inventory tracked at [Stock Locations](inventory.md#stock-locations)
+  - [Product](products.md) — What you sell. A product has variants — the actual buyable items, each with its own price and stock.
+  - [Cart](carts.md) — What a customer is assembling. It changes constantly and is usually abandoned.
+  - [Order](orders.md) — What they committed to. A permanent financial record that must not change quietly.
+  - [Fulfillment](fulfillments.md) — What actually ships. One parcel, from one location, with one tracking number.
 
-2. **Shopping** — Customers add Variants to their cart, creating an [Order](orders.md) with Line Items
 
-3. **Checkout** — The Order collects [Addresses](addresses.md), calculates [Shipping](fulfillments.md) options, and processes [Payments](payments.md)
-
-4. **Fulfillment** — [Shipments](fulfillments.md) are created from Stock Locations, tracking individual [Inventory Units](inventory.md#inventory-units)
-
-5. **Pricing & Adjustments** — [Taxes](taxes.md) and [Promotions](promotions.md) create [Adjustments](taxes-discounts-fees.md) that modify order totals
+```mermaid
+flowchart LR
+    Product --> Variant
+    Variant --> Cart
+    Cart -->|complete| Order
+    Order --> Fulfillment
+    Order --> Payment
+
+    style Cart fill:#e3f2fd,stroke:#0077ff
+    style Order fill:#e8f5e9,stroke:#2e7d32
+```
 
-## Core Model Relationships
+**A cart and an order are separate records**, and that distinction shapes most of the API. A cart tolerates half-finished states — no address yet, no payment chosen. An order has to keep saying what the customer actually agreed to pay, so once it exists, today's prices and promotions can't quietly rewrite it. Completing a cart creates the order.
 
-This diagram shows the key database relationships between Spree's main models:
+## How the pieces relate
 
 ```mermaid
 erDiagram
-    Store ||--o{ Order : "has many"
-    Store ||--o{ Product : "has many"
+    Store ||--o{ Product : "sells"
+    Store ||--o{ Order : "records"
 
     Product ||--o{ Variant : "has many"
-    Product }o--|| TaxCategory : "belongs to"
-    Product }o--|| ShippingCategory : "belongs to"
-    Product }o--o{ Taxon : "categorized by"
+    Product }o--o{ Category : "filed under"
+    Product }o--|| DeliveryProfile : "ships by"
 
-    Variant ||--o{ Price : "has many"
-    Variant ||--o{ StockItem : "has many"
-    Variant ||--o{ LineItem : "has many"
+    Variant ||--o{ Price : "priced in each currency"
+    Variant ||--o{ StockLevel : "stocked at locations"
+    StockLevel }o--|| StockLocation : "held at"
 
-    Order ||--o{ LineItem : "has many"
-    Order ||--o{ Shipment : "has many"
-    Order ||--o{ Payment : "has many"
-    Order ||--o{ Adjustment : "has many"
-    Order }o--|| User : "belongs to"
-    Order }o--|| Address : "ship address"
-    Order }o--|| Address : "bill address"
-
-    Shipment ||--o{ InventoryUnit : "has many"
-    Shipment }o--|| StockLocation : "ships from"
-    Shipment }o--|| ShippingMethod : "via"
+    Cart ||--o{ LineItem : "has many"
+    Cart ||--o| Order : "completes into"
+    LineItem }o--|| Variant : "of"
 
+    Order ||--o{ LineItem : "has many"
+    Order ||--o{ Fulfillment : "shipped as"
+    Order ||--o{ Payment : "paid by"
+    Order ||--o{ TaxLine : "taxed by"
+    Order ||--o{ Discount : "reduced by"
+    Order ||--o{ Fee : "surcharged by"
+    Order }o--|| Customer : "placed by"
+
+    Fulfillment }o--|| DeliveryMethod : "via"
+    Fulfillment }o--|| StockLocation : "ships from"
     Payment }o--|| PaymentMethod : "via"
+```
 
-    StockLocation ||--o{ StockItem : "has many"
+Three things in that diagram are worth calling out, because they're where Spree differs from what you might expect:
 
-    TaxRate }o--|| TaxCategory : "belongs to"
-    TaxRate }o--|| Zone : "applies to"
-    TaxRate ||--o{ Adjustment : "creates"
+**Money added or removed is never one mixed list.** Tax, discounts and fees are three separate kinds of row. "What tax did we charge?" is a direct question with a direct answer instead of a filter over a mixed pile. See [Order totals](order-totals.md).
 
-    Promotion ||--o{ Adjustment : "creates"
-```
+**Delivery is described by a profile, not a category.** A [delivery profile](fulfillments.md) says how a product travels — physically shipped, or digital — and which locations and methods serve it.
 
-## APIs
+**Stock lives per location.** A variant has a stock level at each [stock location](inventory.md), so availability is a real question about real warehouses rather than a single number.
 
-Spree exposes two REST APIs:
+## The two APIs
 
-| API | Purpose | Authentication |
-|-----|---------|----------------|
-| [**Store API**](../../api-reference/store-api/introduction.md) | Customer-facing — cart, checkout, products, account | [Publishable API key + JWT](../../api-reference/store-api/authentication.md) |
-| [**Admin API**](../../api-reference/admin-api/introduction.md) | Operational — manage products, orders, customers, settings | [Secret API key](../../api-reference/admin-api/authentication.md) + JWT |
+```mermaid
+flowchart TB
+    Storefront["Storefront / mobile app"] -->|"@spree/sdk"| StoreAPI["Store API"]
+    BackOffice["Dashboard / integrations"] -->|"@spree/admin-sdk"| AdminAPI["Admin API"]
+    StoreAPI --> Spree[(Spree)]
+    AdminAPI --> Spree
+    Spree --> Webhooks["Webhooks & events"]
+    Webhooks --> External["Your systems"]
+```
 
-Both APIs share the same list shapes, filtering, querying, and pagination, and offer fully typed TypeScript clients — [@spree/sdk](../sdk/quickstart.md) for the Store API and [@spree/admin-sdk](../sdk/admin/quickstart.md) for the Admin API.
+| API | For | Authentication |
+|---|---|---|
+| [**Store API**](../../api-reference/store-api/introduction.md) | Anything a customer touches — browsing, cart, checkout, their account | [Publishable key](../../api-reference/store-api/authentication.md), plus a customer token once signed in |
+| [**Admin API**](../../api-reference/admin-api/introduction.md) | Anything staff or systems touch — catalog, orders, settings | [Secret key](../../api-reference/admin-api/authentication.md) with scopes, or a staff token |
 
-Events from both APIs can trigger [Webhooks](webhooks.md) to notify external systems in real time.
+The split is about exposure, not convenience. A publishable key is safe in browser code because it can only reach what a shopper is allowed to see. A secret key never belongs in a browser.
 
-## Multi-Store Architecture
+Both APIs share the same filtering, pagination and error shapes, so what you learn on one carries to the other. Both return **prefixed IDs** — `prod_86Rf07xd4z`, `cart_k5nR8xLq` — so an ID tells you what it points at.
 
-Spree supports running [multiple storefronts](../multi-tenant/quickstart.md) from a single installation. Each Store can have:
+> **NOTE:** Money is always a **string**: `"135.60"`, never `135.60`. JavaScript can't represent every decimal exactly — `0.1 + 0.2` gives `0.30000000000000004` — which is not something you want inside a price. Every amount also comes formatted for its currency as `display_total`, `display_price` and so on. Render the `display_` one.
 
-- Its own domain and branding
-- Different currencies and locales
-- Separate product catalogs
-- Independent payment and shipping methods
-- Isolated orders and customers
+## Building on top
 
-This makes Spree suitable for multi-brand retailers, international expansion, or B2B/B2C hybrid setups.
+Spree assumes you'll extend it, and gives you three ways in that survive an upgrade:
 
-## Extension Points
+| Approach | Use it for | Guide |
+|---|---|---|
+| **Webhooks** | Telling another system something happened — an ERP, a warehouse, an email tool | [Webhooks](webhooks.md) |
+| **Custom fields** | Storing your own data on a product, order or customer without changing the schema | [Custom Fields](metafields.md) |
+| **Providers** | Plugging in a real service for tax, delivery rates, payments or search | [Providers](../providers/overview.md) |
 
-Spree is designed to be customized without modifying core code. The main extension mechanisms are:
+For merchant-managed data, reach for [custom fields](metafields.md) before anything heavier — they're queryable and editable in the dashboard without touching code.
 
-| Mechanism | Use Case | Documentation |
-|-----------|----------|---------------|
-| **Events & Subscribers** | React to order completion, payment, shipment events | [Events Guide](events.md) |
-| **Webhooks** | Notify external systems of changes | [Webhooks Guide](webhooks.md) |
-| **Dependencies** | Swap out services (tax calculation, shipping estimation) | [Dependencies Guide](../customization/dependencies.md) |
-| **Decorators** | Modify existing core models & classes behavior (use sparingly) | [Decorators Guide](../customization/decorators.md) |
+## Multi-store, multi-market, multi-seller
 
-> **INFO:** For most customizations, prefer **Events** and **Dependencies** over Decorators. They're easier to maintain and won't break during upgrades.
+One Spree installation can run more than one business:
 
-## Packages
+- **[Stores](stores.md)** are separate businesses — their own catalog, orders, customers and settings. Data does not cross between them.
+- **[Channels](channels.md)** are the ways one store sells: a website, a mobile app, a retail till.
+- **[Markets](markets.md)** are the regions a store sells into, each with its currency, locale and tax treatment.
+- **[Sellers](products.md#seller-submissions)** let one store list goods from many vendors, for a marketplace.
 
-Spree is distributed as a set of packages:
+## What you install
 
-**Core (required):**
+| Package | What it is |
+|---|---|
+| `spree` | The engine — catalog, checkout, payments, both APIs |
+| `spree_emails` | Transactional email, if you don't send your own |
+| `spree_dashboard` | The back-office dashboard |
 
-| Package | Purpose |
-|---------|---------|
-| `spree` | Models, services, business logic, Store API, Admin API, and Webhooks |
+Providers for search, delivery rates, tax and payments install separately, so you only carry what you use.
 
-**Optional:**
+**TypeScript:**
 
-| Package | Purpose |
-|---------|---------|
-| `spree_admin` | Admin dashboard for managing your store |
-| `spree_emails` | Transactional email templates (order confirmation, shipping, etc.) |
+| Package | What it is |
+|---|---|
+| [`@spree/sdk`](../sdk/quickstart.md) | Store API client — for your storefront |
+| [`@spree/admin-sdk`](../sdk/admin/quickstart.md) | Admin API client — for back-office and integrations |
+| [`@spree/cli`](../cli/quickstart.md) | Command line for local setup and calling the Admin API |
 
-**TypeScript packages:**
+> **INFO:** Spree runs on PostgreSQL, MySQL or SQLite. PostgreSQL is recommended for production — [database configuration](../deployment/database.md).
 
-| Package | Purpose |
-|---------|---------|
-| [`@spree/sdk`](../sdk/quickstart.md) | TypeScript SDK for the Store API |
-| [`@spree/admin-sdk`](../sdk/admin/quickstart.md) | TypeScript SDK for the Admin API |
-| [`@spree/cli`](../cli/quickstart.md) | Command line interface for managing local environment and using the Admin API from the terminal |
+## Where to go next
 
-## Related Documentation
 
-- [Products](products.md) — Product catalog and variants
-- [Orders](orders.md) — Order lifecycle and state machine
-- [Payments](payments.md) — Payment processing
-- [Shipments](fulfillments.md) — Shipping and fulfillment
-- [Customization Quickstart](../customization/quickstart.md) — How to extend Spree
+  - [Quickstart](../getting-started/quickstart.md) — Get an installation running.
+  - [Store SDK](../sdk/quickstart.md) — Build a storefront against the Store API.
+  - [Products](products.md) — How the catalog is modelled.
+  - [Carts](carts.md) — Cart, checkout, and what completion guarantees.