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 Wizamart 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:

# 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:

# 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:

# 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:

# 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

-- ✅ Correct
inventory
inventory_movements
vendor_users

-- ❌ Incorrect
inventories
inventory_movement
vendorusers

Column Names: Use singular, descriptive names

-- ✅ 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

# ✅ 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

# ✅ 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

# ✅ 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

---

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

---

Quick Reference Table

Component	Naming	Example
API Endpoint Files	PLURAL	products.py, orders.py
Database Models	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	DESCRIPTIVE	auth.py, rate_limiter.py
Database Tables	SINGULAR	product, inventory
Database Columns	SINGULAR	vendor_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 - Development workflow
• Backend Development - Backend development guide
• Architecture Overview - 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 Wizamart multi-tenant ecommerce platform.