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:

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

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

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

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

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

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

-- ✅ Correct
store_users      -- Links stores and users
order_items       -- Links orders and products
product_translations  -- Translations for products

Column Names: Use singular, descriptive names

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

# ✅ 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 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 - 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 Orion multi-tenant ecommerce platform.