424 lines
13 KiB
Markdown
424 lines
13 KiB
Markdown
# 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**:
|
|
```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
|
|
```
|
|
|
|
---
|
|
|
|
## 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](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.
|