updating middleware doc

docs/architecture/middleware.md

@@ -119,6 +119,101 @@ else:
 
 **Why it's needed**: Each vendor shop can have custom branding
 
+## Naming Conventions
+
+### Middleware File Organization
+
+All middleware components follow a consistent naming pattern for maintainability and clarity.
+
+#### File Naming: Simple Nouns Without Redundant Suffixes
+
+**Pattern**: `{purpose}.py` (no "_middleware" suffix)
+
+```
+✅ Good:
+middleware/logging.py
+middleware/context.py
+middleware/auth.py
+
+❌ Avoid:
+middleware/logging_middleware.py
+middleware/context_middleware.py
+middleware/auth_middleware.py
+```
+
+**Rationale**:
+- Keeps names concise and consistent
+- Follows Django, Flask, and FastAPI conventions
+- Makes imports cleaner: `from middleware.logging import LoggingMiddleware`
+- Reduces redundancy (the `middleware/` directory already indicates the purpose)
+
+#### Test File Naming: Mirror the Source File
+
+Test files directly mirror the middleware filename with a `test_` prefix:
+
+```
+middleware/logging.py      → tests/unit/middleware/test_logging.py
+middleware/context.py      → tests/unit/middleware/test_context.py
+middleware/auth.py         → tests/unit/middleware/test_auth.py
+middleware/vendor_context.py → tests/unit/middleware/test_vendor_context.py
+```
+
+#### One Component Per File
+
+Each middleware file contains one primary class or a tightly related set of classes:
+
+```python
+# middleware/logging.py
+class LoggingMiddleware(BaseHTTPMiddleware):
+    """Request/response logging middleware"""
+
+# middleware/context.py
+class ContextManager:              # Business logic
+class ContextMiddleware:           # ASGI wrapper
+class RequestContext(Enum):        # Related enum
+
+# middleware/auth.py
+class AuthManager:                 # Authentication logic
+```
+
+#### One Test File Per Component
+
+Follow the Single Responsibility Principle - each test file tests exactly one component:
+
+```
+✅ Good:
+tests/unit/middleware/test_logging.py      # Tests only LoggingMiddleware
+tests/unit/middleware/test_context.py      # Tests only ContextManager/Middleware
+tests/unit/middleware/test_decorators.py   # Tests only rate_limit decorator
+
+❌ Avoid:
+tests/unit/middleware/test_all_middleware.py  # Tests multiple components
+tests/unit/middleware/test_combined.py        # Violates SRP
+```
+
+**Benefits**:
+- Easy to locate tests for specific components
+- Clear test organization and maintainability
+- Follows unit testing best practices
+- Simplifies test debugging and updates
+
+#### Import Convention
+
+When importing middleware components, use explicit imports:
+
+```python
+# ✅ Preferred - Explicit and clear
+from middleware.logging import LoggingMiddleware
+from middleware.context import ContextManager, RequestContext
+from middleware.auth import AuthManager
+
+# ❌ Avoid - Less clear
+from middleware import logging_middleware
+from middleware import context_middleware
+```
+
+**See**: [Complete Naming Conventions Guide](../development/naming-conventions.md) for project-wide standards.
+
 ## Middleware Execution Order
 
 ### The Stack (First to Last)

docs/backend/middleware-reference.md

@@ -72,7 +72,7 @@ ASGI middleware that wraps VendorContextManager for FastAPI integration.
 
 Enum defining all possible request context types in the application.
 
-::: middleware.context_middleware.RequestContext
+::: middleware.context.RequestContext
     options:
       show_source: false
       heading_level: 4
@@ -95,7 +95,7 @@ Detects the type of request (API, Admin, Vendor Dashboard, Shop) based on URL pa
 - `/shop/` → Shop context
 - Default → Fallback context
 
-::: middleware.context_middleware.ContextManager
+::: middleware.context.ContextManager
     options:
       show_source: false
       heading_level: 4
@@ -105,7 +105,7 @@ Detects the type of request (API, Admin, Vendor Dashboard, Shop) based on URL pa
 
 ASGI middleware for context detection. Must run AFTER VendorContextMiddleware.
 
-::: middleware.context_middleware.ContextMiddleware
+::: middleware.context.ContextMiddleware
     options:
       show_source: false
       heading_level: 4
@@ -192,7 +192,7 @@ Middleware for request/response logging and performance monitoring.
 **Added Headers:**
 - `X-Process-Time`: Request processing duration in seconds
 
-::: middleware.logging_middleware.LoggingMiddleware
+::: middleware.logging.LoggingMiddleware
     options:
       show_source: false
       heading_level: 4

docs/development/naming-conventions.md

@@ -184,23 +184,58 @@ class ProductValidationException(ValidationException):
 
 **Rationale**: Exception files are domain-focused, not collection-focused.
 
-### Middleware Files (DESCRIPTIVE)
+### Middleware Files (SIMPLE NOUNS)
 
-**Rule**: Middleware files use descriptive names based on their function.
+**Rule**: Middleware files use simple, descriptive noun names **without redundant suffixes**.
 
 **Location**: `middleware/`
 
+**Naming Pattern**: `{purpose}.py` (no "_middleware" suffix)
+
 **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
+├── auth.py              # ✅ AuthManager - Authentication & JWT
+├── rate_limiter.py      # ✅ RateLimiter - Request throttling
+├── vendor_context.py    # ✅ VendorContextManager - 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**: Middleware serves specific cross-cutting functions.
+**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_vendor_context.py    # Tests vendor_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
 
@@ -397,7 +432,8 @@ Consider implementing linting rules or pre-commit hooks to enforce:
 | 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` |
+| Middleware | SIMPLE NOUN | `auth.py`, `logging.py`, `context.py` |
+| Middleware Tests | test_{name}.py | `test_auth.py`, `test_logging.py` |
 | Database Tables | SINGULAR | `product`, `inventory` |
 | Database Columns | SINGULAR | `vendor_id`, `created_at` |
 | API Endpoints | PLURAL | `/products`, `/orders` |