orion/docs/development/naming-conventions.md

# Naming Conventions

**Version:** 1.0
**Last Updated:** November 2025
**Audience:** Development Team

---

## Overview

This document establishes consistent naming conventions across the entire Orion multi-tenant ecommerce platform. Consistent naming improves code readability, reduces developer confusion, and ensures maintainable architecture.

## Core Principles

### 1. Context-Based Naming
- **Collections/Endpoints**: Use PLURAL (handle multiple items)
- **Entities/Models**: Use SINGULAR (represent individual items)
- **Domains/Services**: Use SINGULAR (focus on one domain area)

### 2. Terminology Standardization
- Use **"inventory"** not "stock" (more business-friendly)
- Use **"store"** not "shop" (multi-tenant architecture)
- Use **"customer"** not "user" for end customers (clarity)

### 3. File Naming Patterns
- **API files**: `entities.py` (plural)
- **Model files**: `entity.py` (singular)
- **Service files**: `entity_service.py` (singular + service)
- **Exception files**: `entity.py` (singular domain)

---

## Detailed Naming Rules

### API Endpoint Files (PLURAL)

**Rule**: API files handle collections of resources, so use plural names.

**Location**: `app/api/v1/*/`

**Examples**:
```
app/api/v1/admin/
├── stores.py      # Handles multiple stores
├── users.py        # Handles multiple users
└── dashboard.py    # Exception: not a resource collection

app/api/v1/store/
├── products.py     # Handles store's products
├── orders.py       # Handles store's orders
├── customers.py    # Handles store's customers
├── teams.py        # Handles team members
├── inventory.py    # Handles inventory items
└── settings.py     # Exception: not a resource collection

app/api/v1/platform/stores/
├── products.py     # Public product catalog
├── orders.py       # Order placement
└── auth.py         # Exception: authentication service
```

**Rationale**: REST endpoints typically operate on collections (`GET /products`, `POST /orders`).

### Database Model Files (SINGULAR)

**Rule**: Model files represent individual entity definitions, so use singular names.

**Location**: `models/database/`

**Examples**:
```
models/database/
├── user.py         # User, UserProfile classes
├── store.py       # Store, StoreUser, Role classes
├── customer.py     # Customer, CustomerAddress classes
├── product.py      # Product, ProductVariant classes
├── order.py        # Order, OrderItem classes
├── inventory.py    # Inventory, InventoryMovement classes
├── marketplace.py  # MarketplaceImportJob class
└── admin.py        # Admin-specific models
```

**Class Names Within Files**:
```python
# models/database/product.py
class Product(Base):           # Singular
class ProductVariant(Base):    # Singular

# models/database/inventory.py
class Inventory(Base):         # Singular
class InventoryMovement(Base): # Singular
```

**Rationale**: Each model class represents a single entity instance in the database.

### Schema/Pydantic Model Files (SINGULAR)

**Rule**: Schema files define validation for individual entities, so use singular names.

**Location**: `models/schema/`

**Examples**:
```
models/schema/
├── user.py         # UserCreate, UserResponse classes
├── store.py       # StoreCreate, StoreResponse classes
├── customer.py     # CustomerCreate, CustomerResponse classes
├── product.py      # ProductCreate, ProductResponse classes
├── order.py        # OrderCreate, OrderResponse classes
├── inventory.py    # InventoryCreate, InventoryResponse classes
├── marketplace.py  # MarketplaceImportRequest class
└── admin.py        # Admin operation schemas
```

**Class Names Within Files**:
```python
# models/schema/product.py
class ProductCreate(BaseModel):    # Singular entity
class ProductUpdate(BaseModel):    # Singular entity
class ProductResponse(BaseModel):  # Singular entity
```

**Rationale**: Schema models validate individual entity data structures.

### Service Files (SINGULAR + "service")

**Rule**: Service files handle business logic for one domain area, so use singular + "service".

**Location**: `services/`

**Examples**:
```
services/
├── auth_service.py        # Authentication domain
├── admin_service.py       # Admin operations domain
├── store_service.py      # Store management domain
├── customer_service.py    # Customer operations domain
├── team_service.py        # Team management domain
├── product_service.py     # Product operations domain
├── order_service.py       # Order operations domain
├── inventory_service.py   # Inventory operations domain
├── marketplace_service.py # Marketplace integration domain
└── stats_service.py       # Statistics domain
```

**Class Names Within Files**:
```python
# services/product_service.py
class ProductService:      # Singular domain focus
    def create_product()   # Operates on single product
    def get_products()     # Can return multiple, but service is singular
```

**Rationale**: Each service focuses on one business domain area.

### Exception Files (SINGULAR)

**Rule**: Exception files handle errors for one domain area, so use singular names.

**Location**: `app/exceptions/`

**Examples**:
```
app/exceptions/
├── base.py             # Base exception classes
├── handler.py          # Exception handlers
├── auth.py             # Authentication domain exceptions
├── admin.py            # Admin domain exceptions
├── store.py           # Store domain exceptions
├── customer.py         # Customer domain exceptions
├── product.py          # Product domain exceptions
├── order.py            # Order domain exceptions
├── inventory.py        # Inventory domain exceptions
└── marketplace.py      # Marketplace domain exceptions
```

**Class Names Within Files**:
```python
# app/exceptions/product.py
class ProductNotFoundException(ResourceNotFoundException):
class ProductAlreadyExistsException(ConflictException):
class ProductValidationException(ValidationException):
```

**Rationale**: Exception files are domain-focused, not collection-focused.

### Middleware Files (SIMPLE NOUNS)

**Rule**: Middleware files use simple, descriptive noun names **without redundant suffixes**.

**Location**: `middleware/`

**Naming Pattern**: `{purpose}.py` (no "_middleware" suffix)

**Examples**:
```
middleware/
├── auth.py              # ✅ AuthManager - Authentication & JWT
├── rate_limiter.py      # ✅ RateLimiter - Request throttling
├── store_context.py    # ✅ StoreContextManager - Multi-tenant detection
├── context.py           # ✅ ContextManager - Request context detection
├── theme_context.py     # ✅ ThemeContextManager - Theme loading
├── logging.py           # ✅ LoggingMiddleware - Request/response logging
└── decorators.py        # ✅ rate_limit decorator - Cross-cutting concerns
```

**Rationale**:
- Keeps names concise and consistent
- Follows Django, Flask, and FastAPI conventions
- Avoids redundant "_middleware" suffix
- Makes imports cleaner: `from middleware.logging import LoggingMiddleware`

**Test File Naming**: Test files directly mirror the middleware filename:
```
tests/unit/middleware/
├── test_auth.py              # Tests auth.py
├── test_rate_limiter.py      # Tests rate_limiter.py
├── test_store_context.py    # Tests store_context.py
├── test_context.py           # Tests context.py
├── test_theme_context.py     # Tests theme_context.py
├── test_logging.py           # Tests logging.py
└── test_decorators.py        # Tests decorators.py
```

**One Test File Per Component**: Each test file should test **exactly one** middleware component, following the Single Responsibility Principle.

**Class Names Within Files**:
```python
# middleware/logging.py
class LoggingMiddleware(BaseHTTPMiddleware):  # Class name can include "Middleware"
    pass

# middleware/context.py
class ContextManager:                          # Manager for business logic
class ContextMiddleware(BaseHTTPMiddleware):  # Middleware wrapper
```

**Rationale**: Middleware serves specific cross-cutting functions with clean, predictable naming.

### Frontend Files

**Rule**: Frontend files use context-appropriate naming.

**Location**: `frontend/`

**Examples**:
```
frontend/
├── admin/
│   ├── stores.html        # PLURAL - lists multiple stores
│   ├── users.html          # PLURAL - lists multiple users
│   └── dashboard.html      # SINGULAR - one dashboard
├── store/admin/
│   ├── products.html       # PLURAL - lists multiple products
│   ├── orders.html         # PLURAL - lists multiple orders
│   ├── teams.html          # PLURAL - lists team members
│   └── dashboard.html      # SINGULAR - one dashboard
└── shop/
    ├── products.html       # PLURAL - product catalog
    ├── product.html        # SINGULAR - single product detail
    ├── orders.html         # PLURAL - order history
    └── cart.html           # SINGULAR - one shopping cart
```

**Rationale**:
- List views are plural (show collections)
- Detail views are singular (show individual items)
- Functional views use descriptive names

---

## Terminology Standards

### Core Business Terms

| Use This | Not This | Context |
|----------|----------|---------|
| inventory | stock | All inventory management |
| store | shop | Multi-tenant architecture |
| customer | user | End customers (buyers) |
| user | member | Platform/store team members |
| team | staff | Store team members |
| order | purchase | Customer orders |
| product | item | Catalog products |

### Database Naming

**Table Names**: Use plural, lowercase with underscores (industry standard)

Following Rails, Django, Laravel conventions - tables represent collections of entities,
so plural names are natural and read well in SQL queries.

```sql
-- ✅ Correct (plural table names)
users
stores
products
orders
customers
order_items
cart_items
store_users

-- ❌ Incorrect (singular table names)
user
store
product
order
customer
```

**Rationale**:
- A table holds a *collection* of records (many users, many products)
- SQL reads naturally: `SELECT * FROM users WHERE id = 1`
- Follows conventions of most ORMs (ActiveRecord, Django ORM, Laravel Eloquent)
- Used by ~80% of modern web frameworks

**Junction/Join Tables**: Combine both entity names in plural
```sql
-- ✅ Correct
store_users      -- Links stores and users
order_items       -- Links orders and products
product_translations  -- Translations for products
```

**Column Names**: Use singular, descriptive names
```sql
-- ✅ Correct
store_id
inventory_level
created_at

-- ❌ Incorrect
stores_id
inventory_levels
creation_time
```

### API Endpoint Patterns

**Resource Collections**: Use plural nouns
```
GET    /api/v1/store/products      # List products
POST   /api/v1/store/products      # Create product
GET    /api/v1/store/orders        # List orders
POST   /api/v1/store/orders        # Create order
```

**Individual Resources**: Use singular in URL structure
```
GET    /api/v1/store/products/{id}     # Get single product
PUT    /api/v1/store/products/{id}     # Update single product
DELETE /api/v1/store/products/{id}     # Delete single product
```

**Non-Resource Endpoints**: Use descriptive names
```
GET    /api/v1/store/dashboard/stats   # Dashboard statistics
POST   /api/v1/store/auth/login        # Authentication
GET    /api/v1/store/settings          # Store settings
```

---

## Variable and Function Naming

### Function Names

```python
# ✅ Correct - verb + singular object
def create_product()
def get_customer()
def update_order()
def delete_inventory_item()

# ✅ Correct - verb + plural when operating on collections
def get_products()
def list_customers()
def bulk_update_orders()

# ❌ Incorrect
def create_products()     # Creates one product
def get_customers()       # Gets one customer
```

### Variable Names

```python
# ✅ Correct - context-appropriate singular/plural
product = get_product(id)
products = get_products()
customer_list = get_all_customers()
inventory_count = len(inventory_items)

# ❌ Incorrect
products = get_product(id)    # Single item, should be singular
product = get_products()      # Multiple items, should be plural
```

### Class Attributes

```python
# ✅ Correct - descriptive and consistent
class Store:
    id: int
    name: str
    subdomain: str
    owner_user_id: int        # Singular reference
    created_at: datetime

class Customer:
    store_id: int            # Belongs to one store
    total_orders: int         # Aggregate count
    last_order_date: datetime # Most recent
```

---

## Benefits of Consistent Naming

1. **Developer Productivity**: Predictable file locations and naming patterns
2. **Code Readability**: Clear understanding of file purposes and contents
3. **Team Communication**: Shared vocabulary and terminology
4. **Maintenance**: Easier to locate and update related functionality
5. **Onboarding**: New developers quickly understand the codebase structure
6. **Documentation**: Consistent terminology across all documentation
7. **API Usability**: Predictable and intuitive API endpoint structures

---

## Enforcement

### Code Review Checklist

- [ ] File names follow singular/plural conventions
- [ ] Class names use appropriate terminology (inventory vs stock)
- [ ] API endpoints use plural resource names
- [ ] Database table names use plural (industry standard)
- [ ] Variables names match their content (singular vs plural)

### Automated Checks

Consider implementing linting rules or pre-commit hooks to enforce:
- File naming patterns
- Import statement consistency
- Variable naming conventions
- API endpoint patterns

---

## Quick Reference Table

| Component | Naming | Example |
|-----------|--------|---------|
| API Endpoint Files | PLURAL | `products.py`, `orders.py` |
| Database Models (files) | SINGULAR | `product.py`, `order.py` |
| Schema/Pydantic | SINGULAR | `product.py`, `order.py` |
| Services | SINGULAR + service | `product_service.py` |
| Exceptions | SINGULAR | `product.py`, `order.py` |
| Middleware | SIMPLE NOUN | `auth.py`, `logging.py`, `context.py` |
| Middleware Tests | test_{name}.py | `test_auth.py`, `test_logging.py` |
| **Database Tables** | **PLURAL** | `users`, `products`, `orders` |
| Database Columns | SINGULAR | `store_id`, `created_at` |
| API Endpoints | PLURAL | `/products`, `/orders` |
| Functions (single) | SINGULAR | `create_product()` |
| Functions (multiple) | PLURAL | `get_products()` |
| Variables (single) | SINGULAR | `product = ...` |
| Variables (multiple) | PLURAL | `products = ...` |

---

## Related Documentation

- [Contributing Guide](contributing.md) - Development workflow
- [Backend Development](../backend/overview.md) - Backend development guide
- [Architecture Overview](../architecture/overview.md) - System architecture

---

**Document Version:** 1.0
**Last Updated:** November 2025
**Maintained By:** Backend Team

This naming convention guide ensures consistent, maintainable, and intuitive code across the entire Orion multi-tenant ecommerce platform.