orion/6.complete_naming_convention.md

# Multi-Tenant Ecommerce Platform - Complete Naming Convention Guide

## Overview

This document establishes consistent naming conventions across the entire 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 **"vendor"** 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/
├── vendors.py      # Handles multiple vendors
├── users.py        # Handles multiple users
└── dashboard.py    # Exception: not a resource collection

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

app/api/v1/public/vendors/
├── 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
├── vendor.py       # Vendor, VendorUser, 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
├── vendor.py       # VendorCreate, VendorResponse 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
├── vendor_service.py      # Vendor 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
├── vendor.py           # Vendor 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 (DESCRIPTIVE)
**Rule**: Middleware files use descriptive names based on their function.

**Location**: `middleware/`

**Examples**:
```
middleware/
├── auth.py                 # Authentication middleware
├── vendor_context.py       # Vendor context detection
├── rate_limiter.py         # Rate limiting functionality
├── logging_middleware.py   # Request logging
└── decorators.py           # Cross-cutting decorators
```

**Rationale**: Middleware serves specific cross-cutting functions.

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

**Location**: `frontend/`

**Examples**:
```
frontend/
├── admin/
│   ├── vendors.html        # PLURAL - lists multiple vendors
│   ├── users.html          # PLURAL - lists multiple users
│   └── dashboard.html      # SINGULAR - one dashboard
├── vendor/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 |
| vendor | shop | Multi-tenant architecture |
| customer | user | End customers (buyers) |
| user | member | Platform/vendor team members |
| team | staff | Vendor team members |
| order | purchase | Customer orders |
| product | item | Catalog products |

### Database Naming

**Table Names**: Use singular, lowercase with underscores
```sql
-- Correct
inventory
inventory_movements
vendor_users

-- Incorrect  
inventories
inventory_movement
vendorusers
```

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

-- Incorrect
vendors_id
inventory_levels
creation_time
```

### API Endpoint Patterns

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

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

**Non-Resource Endpoints**: Use descriptive names
```
GET    /api/v1/vendor/dashboard/stats   # Dashboard statistics
POST   /api/v1/vendor/auth/login        # Authentication
GET    /api/v1/vendor/settings          # Vendor 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 Vendor:
    id: int
    name: str
    subdomain: str
    owner_user_id: int        # Singular reference
    created_at: datetime

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

## Migration Checklist

When applying these naming conventions to existing code:

### File Renames Required
- [ ] `app/api/v1/stock.py` → `app/api/v1/inventory.py`
- [ ] `models/database/stock.py` → `models/database/inventory.py`
- [ ] `models/schema/stock.py` → `models/schema/inventory.py`
- [ ] `services/stock_service.py` → `services/inventory_service.py`
- [ ] `app/exceptions/stock.py` → `app/exceptions/inventory.py`

### Import Statement Updates
- [ ] Update all `from models.database.stock import` statements
- [ ] Update all `from services.stock_service import` statements
- [ ] Update all `stock_` variable prefixes to `inventory_`

### Class Name Updates
- [ ] `Stock` → `Inventory`
- [ ] `StockMovement` → `InventoryMovement`
- [ ] `StockService` → `InventoryService`

### Database Updates
- [ ] Rename `stock` table to `inventory`
- [ ] Rename `stock_movements` table to `inventory_movements`
- [ ] Update all `stock_id` foreign keys to `inventory_id`

### Frontend Updates
- [ ] Update all HTML files with stock terminology
- [ ] Update JavaScript variable names
- [ ] Update CSS class names if applicable

## 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 models use singular names
- [ ] 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

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