# Terminology Guide

This document defines the standard terminology used throughout the Orion codebase.

## Core Multi-Tenant Entities

| Term | Definition | Database Table | Example |
|------|-----------|---------------|---------|
| **Platform** | The marketplace itself — the top-level entity that hosts merchants | `platforms` | "Letzshop.lu" |
| **Merchant** | A business entity that signs a contract with the platform | `merchants` | "Boulangerie Dupont SARL" |
| **Store** | A specific shop/location operated by a merchant | `stores` | "Boulangerie Dupont - Kirchberg" |
| **Storefront** | The customer-facing view of a store (URL namespace, not a model) | — | `https://dupont.letzshop.lu/` |

## Entity Hierarchy

```
Platform
└── Merchant (the business / legal entity)
    └── Store (the individual shop / brand)
        └── Storefront (customer-facing view — URL namespace only)
```

## Historical Mapping

These terms were renamed from the original codebase terminology:

| Old Term | New Term | Reason |
|----------|----------|--------|
| Company | **Merchant** | "Merchant" is industry-standard (Shopify, Stripe, Square) for the business entity selling on a platform |
| Vendor | **Store** | "Vendor" in e-commerce commonly means "supplier" (someone who sells TO a platform), not a seller on a platform. "Store" is unambiguous. |

## Usage Guidelines

- Use **Merchant** when referring to the business entity, contracts, billing, legal matters
- Use **Store** when referring to the specific shop, its products, inventory, orders, and customer-facing operations
- Use **Storefront** only when referring to the customer-facing URL or display layer
- Never use "Company" or "Vendor" in new code — always use the terms above
