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)