> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Explore how Spree's core models, APIs, and gems fit together — catalog, shopping, checkout, fulfillment, and pricing — for headless or embedded commerce.

## 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 theme={"theme":"night-owl"}
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](/developer/core-concepts/products) have [Variants](/developer/core-concepts/products#variants) (SKUs) with prices and inventory tracked at [Stock Locations](/developer/core-concepts/inventory#stock-locations)

2. **Shopping** — Customers add Variants to their cart, creating an [Order](/developer/core-concepts/orders) with Line Items

3. **Checkout** — The Order collects [Addresses](/developer/core-concepts/addresses), calculates [Shipping](/developer/core-concepts/shipments) options, and processes [Payments](/developer/core-concepts/payments)

4. **Fulfillment** — [Shipments](/developer/core-concepts/shipments) are created from Stock Locations, tracking individual [Inventory Units](/developer/core-concepts/inventory#inventory-units)

5. **Pricing & Adjustments** — [Taxes](/developer/core-concepts/taxes) and [Promotions](/developer/core-concepts/promotions) create [Adjustments](/developer/core-concepts/adjustments) that modify order totals

## Core Model Relationships

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

```mermaid theme={"theme":"night-owl"}
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:

| API                                                    | Purpose                                                    | Authentication                                                       |
| ------------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------- |
| [**Store API**](/api-reference/store-api/introduction) | Customer-facing — cart, checkout, products, account        | [Publishable API key + JWT](/api-reference/store-api/authentication) |
| [**Admin API**](/api-reference/admin-api/introduction) | Operational — manage products, orders, customers, settings | [Secret API key](/api-reference/admin-api/authentication) + JWT      |

Both APIs share the same list shapes, filtering, querying, and pagination, and offer fully typed TypeScript clients — [@spree/sdk](/developer/sdk/quickstart) for the Store API and [@spree/admin-sdk](/developer/sdk/admin/quickstart) for the Admin API.

Events from both APIs can trigger [Webhooks](/developer/core-concepts/webhooks) to notify external systems in real time.

## Multi-Store Architecture

Spree supports running [multiple storefronts](/developer/multi-tenant/quickstart) 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:

| Mechanism                | Use Case                                                       | Documentation                                               |
| ------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------- |
| **Events & Subscribers** | React to order completion, payment, shipment events            | [Events Guide](/developer/core-concepts/events)             |
| **Webhooks**             | Notify external systems of changes                             | [Webhooks Guide](/developer/core-concepts/webhooks)         |
| **Dependencies**         | Swap out services (tax calculation, shipping estimation)       | [Dependencies Guide](/developer/customization/dependencies) |
| **Decorators**           | Modify existing core models & classes behavior (use sparingly) | [Decorators Guide](/developer/customization/decorators)     |

<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):**

| Package | Purpose                                                              |
| ------- | -------------------------------------------------------------------- |
| `spree` | Models, services, business logic, Store API, Admin API, and Webhooks |

**Optional:**

| Package        | Purpose                                                            |
| -------------- | ------------------------------------------------------------------ |
| `spree_admin`  | Admin dashboard for managing your store                            |
| `spree_emails` | Transactional email templates (order confirmation, shipping, etc.) |

**TypeScript packages:**

| Package                                               | Purpose                                                                                         |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [`@spree/sdk`](/developer/sdk/quickstart)             | TypeScript SDK for the Store API                                                                |
| [`@spree/admin-sdk`](/developer/sdk/admin/quickstart) | TypeScript SDK for the Admin API                                                                |
| [`@spree/cli`](/developer/cli/quickstart)             | Command line interface for managing local environment and using the Admin API from the terminal |

## Related Documentation

* [Products](/developer/core-concepts/products) — Product catalog and variants
* [Orders](/developer/core-concepts/orders) — Order lifecycle and state machine
* [Payments](/developer/core-concepts/payments) — Payment processing
* [Shipments](/developer/core-concepts/shipments) — Shipping and fulfillment
* [Customization Quickstart](/developer/customization/quickstart) — How to extend Spree