Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 40 ยท Getting Started

The Core Domain Model

Learn the entities behind every online shop (customers, products, variants, carts, orders, payments, shipments, returns) and how they relate, with Python code.

Before you write a single page or API route, you need words for the things a shop deals with. A domain model is that vocabulary turned into data structures: which entities exist, what each one owns and how they point at each other. Get it right and features such as discounts, partial refunds and split shipments slot in naturally. Get it wrong and every new feature fights the schema.

This lesson walks through the entities that almost every shop has, shows how they relate, and builds a small model in Python with dataclasses. If dataclasses are new to you, read Python dataclasses first. The ideas are language-independent, so you can reuse them in PHP, Java, JavaScript or SQL tables.

The main entities

Here is the cast, roughly in the order a customer meets them.

  • Customer. A person (or company) who buys. Some customers are guests with only an email address; others have accounts.
  • Product. The thing you present on a page: "Trail Backpack". It holds the title, description and images shared by all its versions.
  • Variant. One specific sellable version of a product: "Trail Backpack, green, 20 L". The variant carries the SKU (stock keeping unit), the price and the stock. You never buy a product, you buy a variant.
  • Cart. A temporary, editable list of variants and quantities that a visitor intends to buy.
  • Order. A frozen record of what was bought, at which prices, for whom, and where it goes. Orders are created from carts at checkout.
  • Payment. A record of money movement attached to an order: authorized, captured, refunded. One order can have several payments.
  • Shipment. A parcel leaving a warehouse with some of the order's items and a tracking number. One order can have several shipments.
  • Return. A request to send items back, which may lead to a refund, exchange or store credit.
erDiagram
    CUSTOMER ||--o{ ORDER : places
    PRODUCT ||--|{ VARIANT : has
    CART ||--o{ CART_LINE : contains
    VARIANT ||--o{ CART_LINE : "is added as"
    ORDER ||--|{ ORDER_LINE : contains
    VARIANT ||--o{ ORDER_LINE : "is sold as"
    ORDER ||--o{ PAYMENT : "is paid by"
    ORDER ||--o{ SHIPMENT : "ships in"
    ORDER ||--o{ RETURN : "may have"

The core relationships. Note that an order points at variants only through its own lines.

Read the diagram as sentences. A product has one or more variants. An order has one or more lines, and may have many payments, shipments and returns. Those "one to many" arrows are where beginners most often go wrong, usually by storing a single payment_id or tracking_number directly on the order and then discovering that real life has two of them.

A first model in code

The next stand-in builds a few of these entities and walks from a cart line back to its variant and product. Money is stored as integer cents here; the lesson Representing Money Correctly explains why.

Python Products, variants and a cart

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Two things to notice. Adding the same variant twice increases the quantity of one line rather than creating a duplicate line. And the cart refers to variants by ID, not by copying their data; that is right for a cart, which should always reflect current prices. An order does the opposite, as you will see shortly.

IDs and naming

Every entity needs an identity that never changes.

  • Use an internal ID (an auto-increment integer or a UUID) as the primary key. Foreign keys always use it.
  • Keep human-facing identifiers separate: the SKU for variants, an order number such as #10482 for customers and support staff. People will read these aloud on the phone, so make them short and unambiguous.
  • Never use mutable data as an identity. An email address can change, a product title will be edited, a URL slug may be renamed for SEO.
  • Be careful with sequential public IDs. If /orders/1043 is a valid URL and the next order is 1044, an attacker can guess other customers' orders and a competitor can estimate your sales volume. Use unguessable references in URLs and always check ownership. The security lesson covers this in depth.

Naming matters too. Use the same word everywhere: if the database says variant and the admin says "SKU" and the API says "item", every conversation becomes a translation exercise. Pick one term per concept and write it down. A common set is product, variant, cart_line, order_line, payment, shipment, return.

Orders are snapshots

A cart is a plan; an order is a historical fact. When the order is created you must copy the data that mattered at that moment: title, SKU, unit price, tax, discount and the shipping address. If you only stored a variant_id and looked up the price later, then raising the price next week would silently rewrite last week's invoices.

Python Why an order copies its data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The old order still shows what the customer actually agreed to pay. The same principle applies to addresses (copy them onto the order, do not point at the customer's editable address book) and to tax rates. You keep variant_id as well, so you can still link back for stock, reporting and returns.

One order, many payments and shipments

Real orders are messy, and the model should allow for it:

  • A customer pays half with a gift card and half with a credit card: two payments.
  • One item is in stock and the other is backordered, so the shop ships twice: two shipments, each containing some lines or part of a line.
  • The customer returns one of three identical items: a return that refers to an order line with a quantity of one.
  • A refund happens a month later: another payment-side record, a refund, not a change to the original payment.
flowchart LR
    O["Order #1<br/>3 lines, 1 total"] --> P1["Payment: gift card"]
    O --> P2["Payment: credit card"]
    O --> S1["Shipment A<br/>lines 1 and 2"]
    O --> S2["Shipment B<br/>line 3"]
    S1 --> R["Return<br/>1 unit of line 2"]

One order fans out into several payments, shipments and returns over time.

The practical rule is to record events as new rows instead of overwriting fields. A refund is a new record; a shipment is a new record. Then the history stays intact and the totals can always be recomputed.

Warning: Avoid columns like orders.paid (true/false) and orders.shipped (true/false). They cannot express partial payment, partial shipment or a refund. Derive these facts from the payment and shipment records, or model explicit states, as you will in The Order Lifecycle and State Machines.

Where the model grows

You will extend this core in later lessons without changing its shape: attributes and categories join the product, option axes define the variants (Variants and Options), stock gets its own ledger, discounts and tax lines attach to order lines, and a return gets its own small state machine. When a feature request arrives, a useful first question is "which entity does this belong to, and is it a fact that must be frozen on the order?"

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which entity does a customer actually buy and which carries the SKU?

    A product is the page-level concept; the variant is the specific sellable version with its own SKU, price and stock.
  2. 2. Why does an order line copy the unit price and title instead of only storing a variant ID?

    An order is a historical record. If prices were looked up later, a price change would change old invoices.
  3. 3. A customer pays with a gift card and a credit card for one order. What does that suggest about the model?

    Orders have a one-to-many relationship with payments. A single payment column cannot express split payments.
  4. 4. Which is the best primary key for a customer?

    Emails, names and phone numbers change. Use a stable internal ID and treat the email as an attribute.

Summary

  • The core entities are customer, product, variant, cart, order, payment, shipment and return.
  • You sell variants, not products; the variant owns the SKU, price and stock.
  • Carts reference live catalog data, while orders copy the data that mattered at checkout.
  • An order has many payments, shipments and returns, so record them as separate rows and events.
  • Use stable internal IDs, separate human-facing numbers, and one consistent name per concept.

Next: Representing Money Correctly, where you learn why prices should never be floats.