# 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 **"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 Wizamart multi-tenant ecommerce platform.