revamping documentation
This commit is contained in:
423
docs/development/naming-conventions.md
Normal file
423
docs/development/naming-conventions.md
Normal file
@@ -0,0 +1,423 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user