Back to Spree

Architecture

docs/developer/core-concepts/architecture.mdx

5.4.26.8 KB
Original Source

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.

<Info> Spree supports PostgreSQL, MySQL, and SQLite. PostgreSQL is recommended for production. [Learn more about database configuration](/developer/deployment/database). </Info>

Core Commerce Flow

The following diagram shows how the main models interact during a typical customer purchase:

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. CatalogProducts have Variants (SKUs) with prices and inventory tracked at Stock Locations

  2. Shopping — Customers add Variants to their cart, creating an Order with Line Items

  3. Checkout — The Order collects Addresses, calculates Shipping options, and processes Payments

  4. FulfillmentShipments are created from Stock Locations, tracking individual Inventory Units

  5. Pricing & AdjustmentsTaxes and Promotions create Adjustments that modify order totals

Core Model Relationships

This diagram shows the key database relationships between Spree's main models:

mermaid
erDiagram
    Store ||--o{ Order : "has many"
    Store ||--o{ Product : "has many"

    Product ||--o{ Variant : "has many"
    Product }o--|| TaxCategory : "belongs to"
    Product }o--|| ShippingCategory : "belongs to"
    Product }o--o{ Taxon : "categorized by"

    Variant ||--o{ Price : "has many"
    Variant ||--o{ StockItem : "has many"
    Variant ||--o{ LineItem : "has many"

    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"

    Payment }o--|| PaymentMethod : "via"

    StockLocation ||--o{ StockItem : "has many"

    TaxRate }o--|| TaxCategory : "belongs to"
    TaxRate }o--|| Zone : "applies to"
    TaxRate ||--o{ Adjustment : "creates"

    Promotion ||--o{ Adjustment : "creates"

APIs

Spree exposes two REST APIs, both under API v3:

APIPurposeAuthentication
Store APICustomer-facing — cart, checkout, products, accountPublishable API key + JWT
Admin APIOperational — manage products, orders, customers, settingsSecret API key

Both APIs use prefixed IDs (e.g., prod_86Rf07xd4z, or_m3Rp9wXz), flat JSON request/response structures, and full TypeScript types via the @spree/sdk.

Events from both APIs can trigger Webhooks to notify external systems in real time.

Multi-Store Architecture

Spree supports multiple stores from a single installation. Each Store can have:

  • Its own domain and branding
  • Different currencies and locales
  • Separate product catalogs
  • Independent payment and shipping methods
  • Isolated orders and customers

This makes Spree suitable for multi-brand retailers, international expansion, or B2B/B2C hybrid setups.

Extension Points

Spree is designed to be customized without modifying core code. The main extension mechanisms are:

MechanismUse CaseDocumentation
Events & SubscribersReact to order completion, payment, shipment eventsEvents Guide
WebhooksNotify external systems of changesWebhooks Guide
DependenciesSwap out services (tax calculation, shipping estimation)Dependencies Guide
DecoratorsModify existing model/controller behavior (use sparingly)Decorators Guide
<Info> For most customizations, prefer **Events** and **Dependencies** over Decorators. They're easier to maintain and won't break during upgrades. </Info>

Packages

Spree is distributed as a set of packages:

Core (required):

PackagePurpose
spreeModels, services, business logic, Store API, Admin API, and Webhooks

Optional:

PackagePurpose
spree_adminAdmin dashboard for managing your store
spree_emailsTransactional email templates (order confirmation, shipping, etc.)

TypeScript packages:

PackagePurpose
@spree/sdkTypeScript SDK for Store API and Admin API
<Info> For headless commerce, you only need the `spree` package. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Store API and SDK. </Info>