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
---
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.
canonical: "https://spreecommerce.org/docs/developer/core-concepts/architecture"
---
## 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](/v5/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. **Catalog** — [Products](/v5/developer/core-concepts/products) have [Variants](/v5/developer/core-concepts/products#variants) (SKUs) with prices and inventory tracked at [Stock Locations](/v5/developer/core-concepts/inventory#stock-locations)
2. **Shopping** — Customers add Variants to their cart, creating an [Order](/v5/developer/core-concepts/orders) with Line Items
3. **Checkout** — The Order collects [Addresses](/v5/developer/core-concepts/addresses), calculates [Shipping](/v5/developer/core-concepts/shipments) options, and processes [Payments](/v5/developer/core-concepts/payments)
4. **Fulfillment** — [Shipments](/v5/developer/core-concepts/shipments) are created from Stock Locations, tracking individual [Inventory Units](/v5/developer/core-concepts/inventory#inventory-units)
5. **Pricing & Adjustments** — [Taxes](/v5/developer/core-concepts/taxes) and [Promotions](/v5/developer/core-concepts/promotions) create [Adjustments](/v5/developer/core-concepts/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:
| 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](/v5/developer/sdk/quickstart) for the Store API and [@spree/admin-sdk](/v5/developer/sdk/admin/quickstart) for the Admin API.
Events from both APIs can trigger [Webhooks](/v5/developer/core-concepts/webhooks) to notify external systems in real time.
## Multi-Store Architecture
Spree supports running [multiple storefronts](/v5/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](/v5/developer/core-concepts/events) |
| **Webhooks** | Notify external systems of changes | [Webhooks Guide](/v5/developer/core-concepts/webhooks) |
| **Dependencies** | Swap out services (tax calculation, shipping estimation) | [Dependencies Guide](/v5/developer/customization/dependencies) |
| **Decorators** | Modify existing core models & classes behavior (use sparingly) | [Decorators Guide](/v5/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`](/v5/developer/sdk/quickstart) | TypeScript SDK for the Store API |
| [`@spree/admin-sdk`](/v5/developer/sdk/admin/quickstart) | TypeScript SDK for the Admin API |
| [`@spree/cli`](/v5/developer/cli/quickstart) | Command line interface for managing local environment and using the Admin API from the terminal |
## Related Documentation
- [Products](/v5/developer/core-concepts/products) — Product catalog and variants
- [Orders](/v5/developer/core-concepts/orders) — Order lifecycle and state machine
- [Payments](/v5/developer/core-concepts/payments) — Payment processing
- [Shipments](/v5/developer/core-concepts/shipments) — Shipping and fulfillment
- [Customization Quickstart](/v5/developer/customization/quickstart) — How to extend Spree