refactor: split architecture rules into domain-specific files

Split the monolithic .architecture-rules.yaml (1700+ lines) into focused
domain-specific files in .architecture-rules/ directory:

- _main.yaml: Core config, principles, ignore patterns, severity levels
- api.yaml: API endpoint rules (API-001 to API-005)
- service.yaml: Service layer rules (SVC-001 to SVC-007)
- model.yaml: Model rules (MDL-001 to MDL-004)
- exception.yaml: Exception handling rules (EXC-001 to EXC-005)
- naming.yaml: Naming convention rules (NAM-001 to NAM-005)
- auth.yaml: Auth and multi-tenancy rules (AUTH-*, MT-*)
- middleware.yaml: Middleware rules (MDW-001 to MDW-002)
- frontend.yaml: Frontend rules (JS-*, TPL-*, FE-*, CSS-*)
- language.yaml: Language/i18n rules (LANG-001 to LANG-010)
- quality.yaml: Code quality rules (QUAL-001 to QUAL-003)

Also creates scripts/validators/ module with base classes for future
modular validator extraction.

The validate_architecture.py loader now auto-detects and merges split
YAML files while maintaining backward compatibility with single file mode.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.architecture-rules/_main.yaml

@@ -0,0 +1,102 @@
+# Architecture Rules - Main Configuration
+# This file defines core settings and includes domain-specific rule files.
+
+version: "2.0"
+project: "letzshop-product-import"
+description: "Comprehensive architectural rules for multi-tenant e-commerce platform"
+
+# ============================================================================
+# CORE ARCHITECTURAL PRINCIPLES
+# ============================================================================
+
+principles:
+  - name: "Separation of Concerns"
+    description: "API endpoints should only handle HTTP concerns. Business logic belongs in services."
+
+  - name: "Layered Architecture"
+    description: "Routes → Services → Models. Each layer has specific responsibilities."
+
+  - name: "Type Safety"
+    description: "Use Pydantic models for request/response validation. Use SQLAlchemy models for database."
+
+  - name: "Proper Exception Handling"
+    description: "Services throw domain exceptions. Global handler converts to HTTP responses. Endpoints do NOT catch or raise HTTPException."
+
+  - name: "Multi-Tenancy"
+    description: "All queries must be scoped to vendor_id. No cross-vendor data access."
+
+  - name: "Consistent Naming"
+    description: "API files: plural, Services: singular+service, Models: singular"
+
+# ============================================================================
+# RULE FILE INCLUDES
+# ============================================================================
+
+includes:
+  - api.yaml
+  - service.yaml
+  - model.yaml
+  - exception.yaml
+  - naming.yaml
+  - auth.yaml
+  - middleware.yaml
+  - frontend.yaml
+  - language.yaml
+  - quality.yaml
+
+# ============================================================================
+# VALIDATION SEVERITY LEVELS
+# ============================================================================
+
+severity_levels:
+  error:
+    description: "Critical architectural violation - must be fixed"
+    exit_code: 1
+
+  warning:
+    description: "Pattern deviation - should be fixed"
+    exit_code: 0
+
+  info:
+    description: "Suggestion for improvement"
+    exit_code: 0
+
+# ============================================================================
+# IGNORED PATTERNS
+# ============================================================================
+
+ignore:
+  files:
+    - "**/*_test.py"
+    - "**/test_*.py"
+    - "**/__pycache__/**"
+    - "**/migrations/**"
+    - "**/alembic/versions/**"
+    - "**/node_modules/**"
+    - "**/.venv/**"
+    - "**/venv/**"
+    - ".venv/**"
+    - "venv/**"
+    - "**/build/**"
+    - "**/dist/**"
+
+  patterns:
+    # Allow HTTPException in specific files
+    - file: "app/core/exceptions.py"
+      pattern: "HTTPException"
+      reason: "Exception handling utilities"
+
+    - file: "app/exceptions/handler.py"
+      pattern: "HTTPException"
+      reason: "Exception handler converts to HTTP"
+
+# ============================================================================
+# DOCUMENTATION
+# ============================================================================
+
+documentation:
+  architecture: "docs/architecture/overview.md"
+  backend: "docs/backend/overview.md"
+  frontend: "docs/frontend/overview.md"
+  contributing: "docs/development/contributing.md"
+  code_quality: "docs/development/code-quality.md"

.architecture-rules/api.yaml

@@ -0,0 +1,158 @@
+# Architecture Rules - API Endpoint Rules
+# Rules for app/api/v1/**/*.py files
+
+api_endpoint_rules:
+
+  - id: "API-001"
+    name: "Endpoint must use Pydantic models for request/response"
+    severity: "error"
+    description: |
+      All API endpoints must use Pydantic models (BaseModel) for request bodies
+      and response models. Never use raw dicts or SQLAlchemy models directly.
+
+      WHY THIS MATTERS:
+      - Type safety: Pydantic validates response structure at runtime
+      - Documentation: OpenAPI/Swagger auto-generates accurate docs
+      - Contract stability: Schema changes are explicit and reviewable
+      - IDE support: Consumers get autocomplete and type hints
+      - Prevents bugs: Field name mismatches caught immediately
+
+      COMMON VIOLATION: Service returns dict, frontend expects different field names.
+      Example: Service returns {"total_imports": 5} but frontend expects {"total": 5}.
+      With response_model, this mismatch is caught immediately.
+
+      SCHEMA LOCATION: All response schemas must be defined in models/schema/*.py,
+      never inline in endpoint files. This ensures schemas are reusable and discoverable.
+    pattern:
+      file_pattern: "app/api/v1/**/*.py"
+      anti_patterns:
+        - "return dict"
+        - "-> dict"
+        - "return db_object"
+        - "return {"
+    example_good: |
+      # In models/schema/stats.py
+      class ImportStatsResponse(BaseModel):
+          total: int
+          pending: int
+          completed: int
+          failed: int
+
+      # In app/api/v1/admin/marketplace.py
+      @router.get("/stats", response_model=ImportStatsResponse)
+      def get_import_statistics(db: Session = Depends(get_db)):
+          return stats_service.get_import_statistics(db)
+    example_bad: |
+      # WRONG: No response_model, returns raw dict
+      @router.get("/stats")
+      def get_import_statistics(db: Session = Depends(get_db)):
+          return stats_service.get_import_statistics(db)  # Returns dict
+
+      # WRONG: Schema defined inline in endpoint file
+      class MyResponse(BaseModel):  # Should be in models/schema/
+          ...
+
+      @router.get("/data", response_model=MyResponse)
+      def get_data(): ...
+
+  - id: "API-002"
+    name: "Endpoint must NOT contain business logic"
+    severity: "error"
+    description: |
+      API endpoints should only handle HTTP concerns (validation, auth, response formatting).
+      All business logic must be delegated to service layer.
+
+      Transaction control (db.commit) IS allowed at endpoint level - this is the recommended
+      pattern for request-scoped transactions. One request = one transaction.
+
+      What's NOT allowed:
+      - db.add() - creating entities is business logic
+      - db.query() - complex queries are business logic
+      - db.delete() - deleting entities is business logic
+    pattern:
+      file_pattern: "app/api/v1/**/*.py"
+      anti_patterns:
+        - "db.add("
+        - "db.delete("
+        - "db.query("
+
+  - id: "API-003"
+    name: "Endpoint must NOT raise ANY exceptions directly"
+    severity: "error"
+    description: |
+      API endpoints should NOT raise exceptions directly. Endpoints are a thin
+      orchestration layer that:
+      1. Accepts request parameters (validated by Pydantic)
+      2. Calls dependencies for authentication/authorization (deps.py raises exceptions)
+      3. Calls services for business logic (services raise domain exceptions)
+      4. Returns response (formatted by Pydantic)
+
+      Exception raising belongs in:
+      - Dependencies (app/api/deps.py) - authentication/authorization validation
+      - Services (app/services/) - business logic validation
+
+      The global exception handler catches all WizamartException subclasses and
+      converts them to appropriate HTTP responses.
+
+      WRONG (endpoint raises exception):
+        @router.get("/orders")
+        def get_orders(current_user: User = Depends(get_current_vendor_api)):
+            if not hasattr(current_user, "token_vendor_id"):  # Redundant check
+                raise InvalidTokenException("...")            # Don't raise here
+            return order_service.get_orders(db, current_user.token_vendor_id)
+
+      RIGHT (dependency guarantees, endpoint trusts):
+        @router.get("/orders")
+        def get_orders(current_user: User = Depends(get_current_vendor_api)):
+            # Dependency guarantees token_vendor_id is present
+            return order_service.get_orders(db, current_user.token_vendor_id)
+    pattern:
+      file_pattern: "app/api/v1/**/*.py"
+      anti_patterns:
+        - "raise HTTPException"
+        - "raise InvalidTokenException"
+        - "raise InsufficientPermissionsException"
+        - "if not hasattr\\(current_user.*token_vendor"
+      exceptions:
+        - "app/exceptions/handler.py"
+
+  - id: "API-004"
+    name: "Endpoint must have proper authentication/authorization"
+    severity: "warning"
+    description: |
+      Protected endpoints must use Depends() for authentication.
+      Use get_current_user, get_current_admin, etc.
+
+      Auto-excluded files:
+      - */auth.py - Authentication endpoints (login, logout, register) are intentionally public
+
+      Public endpoint markers (place on line before or after decorator):
+      - # public - Descriptive marker for intentionally unauthenticated endpoints
+      - # noqa: API-004 - Standard noqa style to suppress warning
+
+      Example:
+        # public - Stripe webhook receives external callbacks
+        @router.post("/webhook/stripe")
+        def stripe_webhook(request: Request):
+            ...
+    pattern:
+      file_pattern: "app/api/v1/**/*.py"
+      required_if_not_public:
+        - "Depends(get_current_"
+      auto_exclude_files:
+        - "*/auth.py"
+      public_markers:
+        - "# public"
+        - "# noqa: api-004"
+
+  - id: "API-005"
+    name: "Multi-tenant endpoints must scope queries to vendor_id"
+    severity: "error"
+    description: |
+      All queries in vendor/shop contexts must filter by vendor_id.
+      Use request.state.vendor_id from middleware.
+    pattern:
+      file_pattern: "app/api/v1/vendor/**/*.py"
+      file_pattern: "app/api/v1/shop/**/*.py"
+      discouraged_patterns:
+        - "db.query(.*).all()"

.architecture-rules/auth.yaml

@@ -0,0 +1,87 @@
+# Architecture Rules - Authentication & Authorization Rules
+# Rules for auth patterns and multi-tenancy
+
+auth_rules:
+
+  - id: "AUTH-001"
+    name: "Use JWT tokens in Authorization header"
+    severity: "error"
+    description: |
+      Authentication must use JWT tokens in Authorization: Bearer header
+    pattern:
+      file_pattern: "app/api/**/*.py"
+      enforcement: "middleware"
+
+  - id: "AUTH-002"
+    name: "Role-based access control with Depends"
+    severity: "error"
+    description: |
+      Use Depends(get_current_admin/vendor/customer) for role checks
+    pattern:
+      file_pattern: "app/api/v1/**/*.py"
+      required: "Depends\\(get_current_"
+
+  - id: "AUTH-003"
+    name: "Never store plain passwords"
+    severity: "error"
+    description: |
+      Always hash passwords with bcrypt before storing
+    pattern:
+      file_pattern: "app/services/auth_service.py"
+      required: "bcrypt"
+
+  - id: "AUTH-004"
+    name: "Vendor context pattern - use appropriate dependency for endpoint type"
+    severity: "error"
+    description: |
+      Two vendor context patterns exist - use the appropriate one:
+
+      1. SHOP ENDPOINTS (public, no authentication required):
+         - Use: vendor: Vendor = Depends(require_vendor_context())
+         - Vendor is detected from URL/subdomain/domain
+         - File pattern: app/api/v1/shop/**/*.py
+         - Mark as public with: # public
+
+      2. VENDOR API ENDPOINTS (authenticated):
+         - Use: current_user.token_vendor_id from JWT token
+         - Or use permission dependencies: require_vendor_permission(), require_vendor_owner
+         - These dependencies get vendor from token and set request.state.vendor
+         - File pattern: app/api/v1/vendor/**/*.py
+
+      DEPRECATED for vendor APIs:
+         - require_vendor_context() - only for shop endpoints
+         - getattr(request.state, "vendor", None) without permission dependency
+
+      See: docs/backend/vendor-in-token-architecture.md
+    pattern:
+      file_pattern: "app/api/v1/vendor/**/*.py"
+      anti_patterns:
+        - "require_vendor_context\\(\\)"
+      file_pattern: "app/api/v1/shop/**/*.py"
+      required_patterns:
+        - "require_vendor_context\\(\\)|# public"
+
+# ============================================================================
+# MULTI-TENANCY RULES
+# ============================================================================
+
+multi_tenancy_rules:
+
+  - id: "MT-001"
+    name: "All queries must be scoped to vendor_id"
+    severity: "error"
+    description: |
+      In vendor/shop contexts, all database queries must filter by vendor_id
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      context: "vendor_shop"
+      required_pattern: ".filter\\(.*vendor_id.*\\)"
+
+  - id: "MT-002"
+    name: "No cross-vendor data access"
+    severity: "error"
+    description: |
+      Queries must never access data from other vendors
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      enforcement: "database_query_level"

.architecture-rules/exception.yaml

@@ -0,0 +1,66 @@
+# Architecture Rules - Exception Handling Rules
+# Rules for exception handling across the application
+
+exception_rules:
+
+  - id: "EXC-001"
+    name: "Define custom exceptions in exceptions module"
+    severity: "warning"
+    description: |
+      Create domain-specific exceptions in app/exceptions/ for better
+      error handling and clarity.
+    pattern:
+      file_pattern: "app/exceptions/**/*.py"
+      encouraged_structure: |
+        class VendorError(Exception):
+            """Base exception for vendor-related errors"""
+            pass
+
+  - id: "EXC-002"
+    name: "Never use bare except"
+    severity: "error"
+    description: |
+      Always specify exception types. Bare except catches everything including
+      KeyboardInterrupt and SystemExit.
+    pattern:
+      file_pattern: "**/*.py"
+      anti_patterns:
+        - "except:"
+        - "except\\s*:"
+
+  - id: "EXC-003"
+    name: "Log all exceptions with context"
+    severity: "warning"
+    description: |
+      When catching exceptions, log them with context and stack trace.
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      encouraged_patterns:
+        - "logger.error"
+        - "exc_info=True"
+
+  - id: "EXC-004"
+    name: "Domain exceptions must inherit from WizamartException"
+    severity: "error"
+    description: |
+      All custom domain exceptions must inherit from WizamartException (or its
+      subclasses like ResourceNotFoundException, ValidationException, etc.).
+      This ensures the global exception handler catches and converts them properly.
+    pattern:
+      file_pattern: "app/exceptions/**/*.py"
+      required_base_class: "WizamartException"
+      example_good: |
+        class VendorNotFoundException(ResourceNotFoundException):
+            def __init__(self, vendor_code: str):
+                super().__init__(resource_type="Vendor", identifier=vendor_code)
+
+  - id: "EXC-005"
+    name: "Exception handler must be registered"
+    severity: "error"
+    description: |
+      The global exception handler must be set up in app initialization to
+      catch WizamartException and convert to HTTP responses.
+    pattern:
+      file_pattern: "app/main.py"
+      required_patterns:
+        - "setup_exception_handlers"

.architecture-rules/frontend.yaml

@@ -0,0 +1,539 @@
+# Architecture Rules - Frontend Rules
+# Combined rules for JavaScript, Templates, Components, and Styling
+
+# ============================================================================
+# JAVASCRIPT ARCHITECTURE RULES
+# ============================================================================
+
+javascript_rules:
+
+  - id: "JS-001"
+    name: "Use centralized logger, not console"
+    severity: "error"
+    description: |
+      Use window.LogConfig.createLogger() for consistent logging.
+      Never use console.log, console.error, console.warn directly.
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      anti_patterns:
+        - "console\\.log"
+        - "console\\.error"
+        - "console\\.warn"
+      exceptions:
+        - "// eslint-disable"
+        - "console.log('✅"
+      auto_exclude_files:
+        - "init-*.js"
+
+  - id: "JS-002"
+    name: "Use lowercase apiClient for API calls"
+    severity: "error"
+    description: |
+      Use lowercase 'apiClient' consistently, not 'ApiClient' or 'API_CLIENT'
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      anti_patterns:
+        - "ApiClient\\."
+        - "API_CLIENT\\."
+      required_pattern: "apiClient\\."
+
+  - id: "JS-003"
+    name: "Alpine components must spread ...data()"
+    severity: "error"
+    description: |
+      All Alpine.js components must inherit base layout data using spread operator
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      required_in_alpine_components:
+        - "\\.\\.\\.data\\(\\)"
+
+  - id: "JS-004"
+    name: "Alpine components must set currentPage"
+    severity: "error"
+    description: |
+      All Alpine.js page components must set a currentPage identifier
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      required_in_alpine_components:
+        - "currentPage:"
+
+  - id: "JS-005"
+    name: "Initialization methods must include guard"
+    severity: "error"
+    description: |
+      Init methods should prevent duplicate initialization with guard
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      recommended_pattern: |
+        if (window._pageInitialized) return;
+        window._pageInitialized = true;
+
+  - id: "JS-006"
+    name: "All async operations must have try/catch with error logging"
+    severity: "error"
+    description: |
+      All API calls and async operations must have error handling
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      check: "async_error_handling"
+
+  - id: "JS-007"
+    name: "Set loading state before async operations"
+    severity: "warning"
+    description: |
+      Loading state should be set before and cleared after async operations
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      recommended_pattern: |
+        loading = true;
+        try {
+          // operation
+        } finally {
+          loading = false;
+        }
+
+  - id: "JS-008"
+    name: "Use apiClient for API calls, not raw fetch()"
+    severity: "error"
+    description: |
+      All API calls must use the apiClient helper instead of raw fetch().
+      The apiClient automatically:
+      - Adds Authorization header with JWT token from cookies
+      - Sets Content-Type headers
+      - Handles error responses consistently
+      - Provides logging integration
+
+      WRONG (raw fetch):
+        const response = await fetch('/api/v1/admin/products/123');
+
+      RIGHT (apiClient):
+        const response = await apiClient.get('/admin/products/123');
+        const result = await apiClient.post('/admin/products', data);
+        await apiClient.delete('/admin/products/123');
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      anti_patterns:
+        - "fetch\\('/api/"
+        - 'fetch\\("/api/'
+        - "fetch\\(`/api/"
+      exceptions:
+        - "init-api-client.js"
+
+  - id: "JS-009"
+    name: "Use Utils.showToast() for notifications, not alert() or window.showToast"
+    severity: "error"
+    description: |
+      All user notifications must use Utils.showToast() from static/shared/js/utils.js.
+      Never use browser alert() dialogs or undefined window.showToast.
+
+      Utils.showToast() provides:
+      - Consistent styling (Tailwind-based toast in bottom-right corner)
+      - Automatic fade-out after duration
+      - Color-coded types (success=green, error=red, warning=yellow, info=blue)
+
+      WRONG (browser dialog):
+        alert('Product saved successfully');
+
+      RIGHT (Utils helper):
+        Utils.showToast('Product saved successfully', 'success');
+        Utils.showToast('Failed to save product', 'error');
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      anti_patterns:
+        - "alert\\("
+        - "window\\.showToast"
+      exceptions:
+        - "utils.js"
+
+# ============================================================================
+# TEMPLATE RULES (Jinja2)
+# ============================================================================
+
+template_rules:
+
+  - id: "TPL-001"
+    name: "Admin templates must extend admin/base.html"
+    severity: "error"
+    description: |
+      All admin templates must extend the base template for consistency.
+
+      Auto-excluded files:
+      - login.html - Standalone login page (no sidebar/navigation)
+      - errors/*.html - Error pages extend errors/base.html instead
+      - test-*.html - Test/development templates
+
+      Standalone template markers (place in first 5 lines):
+      - {# standalone #} - Mark template as intentionally standalone
+      - {# noqa: TPL-001 #} - Standard noqa style to suppress error
+      - <!-- standalone --> - HTML comment style
+    pattern:
+      file_pattern: "app/templates/admin/**/*.html"
+      required_patterns:
+        - "{% extends ['\"]admin/base\\.html['\"] %}"
+      auto_exclude_files:
+        - "login.html"
+        - "errors/"
+        - "test-"
+      standalone_markers:
+        - "{# standalone #}"
+        - "{# noqa: tpl-001 #}"
+        - "<!-- standalone -->"
+      exceptions:
+        - "base.html"
+        - "partials/"
+
+  - id: "TPL-002"
+    name: "Vendor templates must extend vendor/base.html"
+    severity: "error"
+    description: "All vendor templates must extend the base template"
+    pattern:
+      file_pattern: "app/templates/vendor/**/*.html"
+      required_patterns:
+        - "{% extends ['\"]vendor/base\\.html['\"] %}"
+      exceptions:
+        - "base.html"
+        - "partials/"
+
+  - id: "TPL-003"
+    name: "Shop templates must extend shop/base.html"
+    severity: "error"
+    description: "All shop templates must extend the base template"
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      required_patterns:
+        - "{% extends ['\"]shop/base\\.html['\"] %}"
+      exceptions:
+        - "base.html"
+        - "partials/"
+
+  - id: "TPL-004"
+    name: "Use x-text for dynamic text content (prevents XSS)"
+    severity: "warning"
+    description: |
+      Use x-text directive for dynamic content to prevent XSS vulnerabilities
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      recommended_pattern: '<p x-text="item.name"></p>'
+
+  - id: "TPL-005"
+    name: "Use x-html ONLY for safe content"
+    severity: "error"
+    description: |
+      Use x-html only for trusted content like icons, never for user-generated content
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      safe_usage:
+        - 'x-html="\\$icon\\('
+
+  - id: "TPL-006"
+    name: "Implement loading state for data loads"
+    severity: "warning"
+    description: |
+      All templates that load data should show loading state
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      recommended_pattern: '<div x-show="loading">Loading...</div>'
+
+  - id: "TPL-007"
+    name: "Implement empty state when no data"
+    severity: "warning"
+    description: |
+      Show empty state when lists have no items
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      recommended_pattern: '<template x-if="items.length === 0">No items</template>'
+
+# ============================================================================
+# FRONTEND COMPONENT RULES
+# ============================================================================
+
+frontend_component_rules:
+
+  - id: "FE-001"
+    name: "Use pagination macro instead of inline HTML"
+    severity: "warning"
+    description: |
+      Use the shared pagination macro instead of duplicating pagination HTML.
+      Import from shared/macros/pagination.html.
+
+      RIGHT (use macro):
+        {% from 'shared/macros/pagination.html' import pagination %}
+        {{ pagination() }}
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      anti_patterns:
+        - 'aria-label="Table navigation"'
+        - "previousPage\\(\\).*nextPage\\(\\)"
+      exceptions:
+        - "shared/macros/pagination.html"
+        - "components.html"
+
+  - id: "FE-002"
+    name: "Use $icon() helper instead of inline SVGs"
+    severity: "warning"
+    description: |
+      Use the Alpine.js $icon() helper for consistent iconography.
+      Do not use inline <svg> elements.
+
+      RIGHT (icon helper):
+        <span x-html="$icon('arrow-left', 'w-4 h-4')"></span>
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      anti_patterns:
+        - "<svg.*viewBox.*>.*</svg>"
+      exceptions:
+        - "base.html"
+        - "components.html"
+        - "shared/macros/"
+
+  - id: "FE-003"
+    name: "Use table macros for consistent table styling"
+    severity: "info"
+    description: |
+      Use the shared table macros for consistent table styling.
+      Import from shared/macros/tables.html.
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/tables.html' import"
+
+  - id: "FE-004"
+    name: "Use form macros for consistent form styling"
+    severity: "info"
+    description: |
+      Use the shared form macros for consistent input styling and validation.
+      Import from shared/macros/forms.html.
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/forms.html' import"
+
+  - id: "FE-008"
+    name: "Use number_stepper macro for quantity inputs"
+    severity: "warning"
+    description: |
+      Use the shared number_stepper macro instead of raw <input type="number">.
+      This ensures consistent styling, proper dark mode support, and hides
+      native browser spinners that render inconsistently.
+
+      RIGHT (use macro):
+        {% from 'shared/macros/inputs.html' import number_stepper %}
+        {{ number_stepper(model='quantity', min=1, max=99) }}
+
+      Suppress with:
+        - {# noqa: FE-008 #} on the line or at file level
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      anti_patterns:
+        - 'type="number"'
+        - "type='number'"
+      exceptions:
+        - "shared/macros/inputs.html"
+        - "components.html"
+
+  - id: "FE-009"
+    name: "Use product_card macro for product displays"
+    severity: "info"
+    description: |
+      Use the shared product_card macro for consistent product presentation.
+      Import from shared/macros/shop/product-card.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/product-card.html' import"
+
+  - id: "FE-010"
+    name: "Use product_grid macro for product listings"
+    severity: "info"
+    description: |
+      Use the shared product_grid macro for responsive product grids.
+      Import from shared/macros/shop/product-grid.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/product-grid.html' import"
+
+  - id: "FE-011"
+    name: "Use add_to_cart macros for cart interactions"
+    severity: "info"
+    description: |
+      Use the shared add-to-cart macros for consistent cart functionality.
+      Import from shared/macros/shop/add-to-cart.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/add-to-cart.html' import"
+
+  - id: "FE-012"
+    name: "Use mini_cart macro for cart dropdown"
+    severity: "info"
+    description: |
+      Use the shared mini_cart macros for header cart functionality.
+      Import from shared/macros/shop/mini-cart.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/mini-cart.html' import"
+
+  - id: "FE-013"
+    name: "Use product_gallery macro for image galleries"
+    severity: "info"
+    description: |
+      Use the shared product_gallery macros for product image displays.
+      Import from shared/macros/shop/product-gallery.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/product-gallery.html' import"
+
+  - id: "FE-014"
+    name: "Use variant_selector macros for product options"
+    severity: "info"
+    description: |
+      Use the shared variant_selector macros for product variant selection.
+      Import from shared/macros/shop/variant-selector.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/variant-selector.html' import"
+
+  - id: "FE-015"
+    name: "Use product_info macros for product details"
+    severity: "info"
+    description: |
+      Use the shared product_info macros for product detail sections.
+      Import from shared/macros/shop/product-info.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/product-info.html' import"
+
+  - id: "FE-016"
+    name: "Use product_tabs macro for product content tabs"
+    severity: "info"
+    description: |
+      Use the shared product_tabs macros for tabbed product information.
+      Import from shared/macros/shop/product-tabs.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/product-tabs.html' import"
+
+  - id: "FE-017"
+    name: "Use category_nav macros for category navigation"
+    severity: "info"
+    description: |
+      Use the shared category_nav macros for category navigation sidebars and menus.
+      Import from shared/macros/shop/category-nav.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/category-nav.html' import"
+
+  - id: "FE-018"
+    name: "Use breadcrumbs macros for breadcrumb navigation"
+    severity: "info"
+    description: |
+      Use the shared breadcrumbs macros for navigation trails.
+      Import from shared/macros/shop/breadcrumbs.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/breadcrumbs.html' import"
+
+  - id: "FE-019"
+    name: "Use search_bar macros for product search"
+    severity: "info"
+    description: |
+      Use the shared search_bar macros for product search functionality.
+      Import from shared/macros/shop/search-bar.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/search-bar.html' import"
+
+  - id: "FE-020"
+    name: "Use filter_sidebar macros for product filtering"
+    severity: "info"
+    description: |
+      Use the shared filter_sidebar macros for product filtering panels.
+      Import from shared/macros/shop/filter-sidebar.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/filter-sidebar.html' import"
+
+  - id: "FE-021"
+    name: "Use star_rating macros for rating displays"
+    severity: "info"
+    description: |
+      Use the shared star_rating macros for all rating displays and inputs.
+      Import from shared/macros/shop/star-rating.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/star-rating.html' import"
+
+  - id: "FE-022"
+    name: "Use review macros for review displays"
+    severity: "info"
+    description: |
+      Use the shared review macros for product reviews.
+      Import from shared/macros/shop/reviews.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/reviews.html' import"
+
+  - id: "FE-023"
+    name: "Use trust_badges macros for trust signals"
+    severity: "info"
+    description: |
+      Use the shared trust_badges macros for security and trust indicators.
+      Import from shared/macros/shop/trust-badges.html.
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/trust-badges.html' import"
+
+# ============================================================================
+# FRONTEND STYLING RULES
+# ============================================================================
+
+styling_rules:
+
+  - id: "CSS-001"
+    name: "Use Tailwind utility classes"
+    severity: "warning"
+    description: |
+      Prefer Tailwind utility classes over custom CSS
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      encouraged: true
+
+  - id: "CSS-002"
+    name: "Support dark mode with dark: prefix"
+    severity: "warning"
+    description: |
+      All color classes should include dark mode variants
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      recommended_pattern: 'class="bg-white dark:bg-gray-800"'
+
+  - id: "CSS-003"
+    name: "Shop templates use vendor theme CSS variables"
+    severity: "error"
+    description: |
+      Shop templates must use CSS variables for vendor-specific theming
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      required_pattern: 'var\\(--color-primary\\)'
+
+  - id: "CSS-004"
+    name: "Mobile-first responsive design"
+    severity: "warning"
+    description: |
+      Use mobile-first responsive classes
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      recommended_pattern: 'class="grid-cols-1 md:grid-cols-2 lg:grid-cols-4"'

.architecture-rules/language.yaml

@@ -0,0 +1,240 @@
+# Architecture Rules - Language & I18N Rules
+# Rules for internationalization and language handling
+
+language_rules:
+
+  - id: "LANG-001"
+    name: "Only use supported language codes"
+    severity: "error"
+    description: |
+      Only use supported language codes: en, fr, de, lb
+      Never use full language names or invalid codes.
+
+      SUPPORTED CODES:
+      - en: English (fallback language)
+      - fr: French (default for Luxembourg)
+      - de: German
+      - lb: Luxembourgish
+
+      WRONG:
+        language = "english"  # Use "en"
+        language = "french"   # Use "fr"
+        language = "lux"      # Use "lb"
+
+      RIGHT:
+        language = "en"
+        language = "fr"
+        language = "de"
+        language = "lb"
+    pattern:
+      file_pattern: "**/*.py"
+      anti_patterns:
+        - "'english'"
+        - "'french'"
+        - "'german'"
+        - "'luxembourgish'"
+        - "'lux'"
+
+  - id: "LANG-002"
+    name: "Never use inline Alpine.js x-data with Jinja for language selector"
+    severity: "error"
+    description: |
+      Never put complex JavaScript objects inline in x-data when using Jinja variables.
+      Jinja outputs Python lists, not JSON, which breaks JavaScript parsing.
+
+      WRONG (inline with Jinja):
+        <div x-data="{
+            languages: {{ vendor.storefront_languages }},
+            ...
+        }">
+
+      RIGHT (function with tojson|safe):
+        <div x-data="languageSelector('{{ lang }}', {{ langs|tojson|safe }})">
+
+      The languageSelector function must be defined in:
+      - static/shop/js/shop-layout.js (for storefront)
+      - static/vendor/js/init-alpine.js (for vendor dashboard)
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      anti_patterns:
+        - 'x-data="{\s*.*languages:'
+        - 'x-data="{\s*.*languageNames:'
+        - 'x-data="{\s*.*languageFlags:'
+      exceptions:
+        - "partials/header.html"
+
+  - id: "LANG-003"
+    name: "Use tojson|safe for Python lists in JavaScript"
+    severity: "error"
+    description: |
+      When passing Python lists to JavaScript in templates, always use tojson|safe.
+      - tojson converts Python list to JSON
+      - safe prevents HTML escaping of quotes
+
+      WRONG (raw output):
+        languages: {{ vendor.storefront_languages }}
+        <!-- Outputs: ['fr', 'de'] - Python syntax -->
+
+      WRONG (tojson without safe):
+        languages: {{ vendor.storefront_languages|tojson }}
+        <!-- May escape quotes to &quot; -->
+
+      RIGHT:
+        languages: {{ vendor.storefront_languages|tojson|safe }}
+        <!-- Outputs: ["fr", "de"] - Valid JSON -->
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      required_with_jinja_array:
+        - "|tojson|safe"
+
+  - id: "LANG-004"
+    name: "Language selector function must be exported to window"
+    severity: "error"
+    description: |
+      The languageSelector function must be defined and exported to window
+      in the appropriate JavaScript file.
+
+      Required in static/shop/js/shop-layout.js:
+        function languageSelector(currentLang, enabledLanguages) { ... }
+        window.languageSelector = languageSelector;
+
+      Required in static/vendor/js/init-alpine.js:
+        function languageSelector(currentLang, enabledLanguages) { ... }
+        window.languageSelector = languageSelector;
+    pattern:
+      file_pattern: "static/shop/js/shop-layout.js"
+      required_patterns:
+        - "function languageSelector"
+        - "window.languageSelector"
+      file_pattern: "static/vendor/js/init-alpine.js"
+      required_patterns:
+        - "function languageSelector"
+        - "window.languageSelector"
+
+  - id: "LANG-005"
+    name: "Use native language names in language selector"
+    severity: "error"
+    description: |
+      Language names must be in their native form, not English.
+
+      WRONG (English names):
+        languageNames: {
+            'fr': 'French',
+            'de': 'German',
+            'lb': 'Luxembourgish'
+        }
+
+      RIGHT (native names):
+        languageNames: {
+            'en': 'English',
+            'fr': 'Francais',
+            'de': 'Deutsch',
+            'lb': 'Letzebuergesch'
+        }
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      anti_patterns:
+        - "'fr':\\s*'French'"
+        - "'de':\\s*'German'"
+        - "'lb':\\s*'Luxembourgish'"
+
+  - id: "LANG-006"
+    name: "Use correct flag codes for languages"
+    severity: "error"
+    description: |
+      Flag codes must map correctly to flag-icons library codes.
+
+      CORRECT MAPPINGS:
+      - en -> gb (Great Britain flag for English)
+      - fr -> fr (France flag)
+      - de -> de (Germany flag)
+      - lb -> lu (Luxembourg flag)
+
+      WRONG:
+        'en': 'us'  # US flag incorrect for general English
+        'en': 'en'  # 'en' is not a valid flag code
+        'lb': 'lb'  # 'lb' is not a valid flag code
+
+      RIGHT:
+        'en': 'gb',
+        'fr': 'fr',
+        'de': 'de',
+        'lb': 'lu'
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      anti_patterns:
+        - "'en':\\s*'us'"
+        - "'en':\\s*'en'"
+        - "'lb':\\s*'lb'"
+
+  - id: "LANG-007"
+    name: "Storefront must respect vendor's enabled languages"
+    severity: "error"
+    description: |
+      Shop/storefront templates must only show languages enabled by the vendor.
+      Use vendor.storefront_languages, not a hardcoded list.
+
+      WRONG (hardcoded):
+        {% set enabled_langs = ['en', 'fr', 'de', 'lb'] %}
+
+      RIGHT (from vendor config):
+        {% set enabled_langs = vendor.storefront_languages if vendor and vendor.storefront_languages else ['fr', 'de', 'en'] %}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      required_for_lang_selector:
+        - "vendor.storefront_languages"
+
+  - id: "LANG-008"
+    name: "Language API endpoint must use POST method"
+    severity: "error"
+    description: |
+      The language set API must be called with POST method, not GET.
+
+      WRONG:
+        fetch('/api/v1/language/set?lang=' + lang)
+        fetch('/api/v1/language/set', { method: 'GET' })
+
+      RIGHT:
+        fetch('/api/v1/language/set', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ language: lang })
+        })
+    pattern:
+      file_pattern: "static/**/js/**/*.js"
+      anti_patterns:
+        - "/language/set.*method.*GET"
+        - "/language/set\\?lang="
+
+  - id: "LANG-009"
+    name: "Always provide language default in templates"
+    severity: "error"
+    description: |
+      When accessing request.state.language, always provide a default value.
+
+      WRONG:
+        {{ request.state.language }}  <!-- May be None -->
+
+      RIGHT:
+        {{ request.state.language|default("fr") }}
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      anti_patterns:
+        - 'request\\.state\\.language[^|]'
+      required_pattern: 'request\\.state\\.language\\|default'
+
+  - id: "LANG-010"
+    name: "Translation files must be valid JSON"
+    severity: "error"
+    description: |
+      All translation files in static/locales/ must be valid JSON.
+      No trailing commas, proper quoting, etc.
+
+      Files required:
+      - static/locales/en.json
+      - static/locales/fr.json
+      - static/locales/de.json
+      - static/locales/lb.json
+    pattern:
+      file_pattern: "static/locales/*.json"
+      check: "valid_json"

.architecture-rules/middleware.yaml

@@ -0,0 +1,22 @@
+# Architecture Rules - Middleware Rules
+# Rules for middleware/**/*.py files
+
+middleware_rules:
+
+  - id: "MDW-001"
+    name: "Middleware files use simple nouns without _middleware suffix"
+    severity: "warning"
+    description: |
+      Middleware files should be named with simple nouns (auth.py, not auth_middleware.py)
+    pattern:
+      file_pattern: "middleware/**/*.py"
+      check: "middleware_naming"
+
+  - id: "MDW-002"
+    name: "Vendor context must be injected for vendor/shop routes"
+    severity: "error"
+    description: |
+      Vendor context middleware must set request.state.vendor_id and request.state.vendor
+    pattern:
+      file_pattern: "middleware/vendor_context.py"
+      required: true

.architecture-rules/model.yaml

@@ -0,0 +1,55 @@
+# Architecture Rules - Model Rules
+# Rules for models/database/*.py and models/schema/*.py files
+
+model_rules:
+
+  - id: "MDL-001"
+    name: "Database models must use SQLAlchemy Base"
+    severity: "error"
+    description: |
+      All database models must inherit from SQLAlchemy Base and use proper
+      column definitions with types and constraints.
+    pattern:
+      file_pattern: "models/database/**/*.py"
+      required_patterns:
+        - "class.*\\(Base\\):"
+
+  - id: "MDL-002"
+    name: "Use Pydantic models separately from SQLAlchemy models"
+    severity: "error"
+    description: |
+      Never mix SQLAlchemy and Pydantic in the same model.
+      SQLAlchemy = database schema, Pydantic = API validation/serialization.
+    pattern:
+      file_pattern: "models/**/*.py"
+      anti_patterns:
+        - "class.*\\(Base, BaseModel\\):"
+
+  - id: "MDL-003"
+    name: "Pydantic models must use from_attributes for ORM mode"
+    severity: "error"
+    description: |
+      Pydantic response models must enable from_attributes to work with SQLAlchemy models.
+    pattern:
+      file_pattern: "models/schema/**/*.py"
+      required_in_response_models:
+        - "from_attributes = True"
+
+  - id: "MDL-004"
+    name: "Database tables use plural names"
+    severity: "warning"
+    description: |
+      Database table names should be plural lowercase following industry standard
+      conventions (Rails, Django, Laravel, most ORMs). A table represents a
+      collection of entities, so plural names are natural: 'users', 'orders',
+      'products'. This reads naturally in SQL: SELECT * FROM users WHERE id = 1.
+
+      Examples:
+        - Good: users, vendors, products, orders, order_items, cart_items
+        - Bad: user, vendor, product, order
+
+      Junction/join tables use both entity names in plural:
+        - Good: vendor_users, order_items, product_translations
+    pattern:
+      file_pattern: "models/database/**/*.py"
+      check: "table_naming_plural"

.architecture-rules/naming.yaml

@@ -0,0 +1,56 @@
+# Architecture Rules - Naming Convention Rules
+# Rules for consistent naming across the codebase
+
+naming_rules:
+
+  - id: "NAM-001"
+    name: "API files use PLURAL names"
+    severity: "error"
+    description: |
+      API endpoint files should use plural names (vendors.py, products.py)
+    pattern:
+      file_pattern: "app/api/v1/**/*.py"
+      check: "plural_naming"
+      exceptions:
+        - "__init__.py"
+        - "auth.py"
+        - "health.py"
+
+  - id: "NAM-002"
+    name: "Service files use SINGULAR + 'service' suffix"
+    severity: "error"
+    description: |
+      Service files should use singular name + _service (vendor_service.py)
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      check: "service_naming"
+
+  - id: "NAM-003"
+    name: "Model files use SINGULAR names"
+    severity: "error"
+    description: |
+      Both database and schema model files use singular names (product.py)
+    pattern:
+      file_pattern: "models/**/*.py"
+      check: "singular_naming"
+
+  - id: "NAM-004"
+    name: "Use consistent terminology: vendor not shop"
+    severity: "warning"
+    description: |
+      Use 'vendor' consistently, not 'shop' (except for shop frontend)
+    pattern:
+      file_pattern: "app/**/*.py"
+      discouraged_terms:
+        - "shop_id"
+        - "shop_service"
+
+  - id: "NAM-005"
+    name: "Use consistent terminology: inventory not stock"
+    severity: "warning"
+    description: |
+      Use 'inventory' consistently, not 'stock'
+    pattern:
+      file_pattern: "app/**/*.py"
+      discouraged_terms:
+        - "stock_service"

.architecture-rules/quality.yaml

@@ -0,0 +1,27 @@
+# Architecture Rules - Code Quality Rules
+# Rules for code quality, formatting, and linting
+
+code_quality_rules:
+
+  - id: "QUAL-001"
+    name: "All code must be formatted with Ruff"
+    severity: "error"
+    description: |
+      Run 'make format' before committing
+    enforcement: "pre_commit"
+
+  - id: "QUAL-002"
+    name: "All code must pass Ruff linting"
+    severity: "error"
+    description: |
+      Run 'make lint' before committing
+    enforcement: "pre_commit"
+
+  - id: "QUAL-003"
+    name: "Type hints recommended for functions"
+    severity: "warning"
+    description: |
+      Add type hints to function parameters and return types
+    pattern:
+      file_pattern: "app/**/*.py"
+      encouraged: true

.architecture-rules/service.yaml

@@ -0,0 +1,117 @@
+# Architecture Rules - Service Layer Rules
+# Rules for app/services/**/*.py files
+
+service_layer_rules:
+
+  - id: "SVC-001"
+    name: "Service must NOT raise HTTPException"
+    severity: "error"
+    description: |
+      Services are business logic layer - they should NOT know about HTTP.
+      Raise domain-specific exceptions instead (ValueError, custom exceptions).
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      anti_patterns:
+        - "raise HTTPException"
+        - "from fastapi import HTTPException"
+
+  - id: "SVC-002"
+    name: "Service must use proper exception handling"
+    severity: "error"
+    description: |
+      Services should raise meaningful domain exceptions, not generic Exception.
+      Create custom exception classes for business rule violations.
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      discouraged_patterns:
+        - "raise Exception\\("
+
+  - id: "SVC-003"
+    name: "Service methods must accept db session as parameter"
+    severity: "error"
+    description: |
+      Service methods should receive database session as a parameter for testability
+      and transaction control. Never create session inside service.
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      required_in_method_signature:
+        - "db: Session"
+      anti_patterns:
+        - "SessionLocal()"
+        - "get_db()"
+
+  - id: "SVC-004"
+    name: "Service must use Pydantic models for input validation"
+    severity: "warning"
+    description: |
+      Service methods should accept Pydantic models for complex inputs
+      to ensure type safety and validation.
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      encouraged_patterns:
+        - "BaseModel"
+
+  - id: "SVC-005"
+    name: "Service must scope queries to vendor_id in multi-tenant contexts"
+    severity: "error"
+    description: |
+      All database queries must be scoped to vendor_id to prevent cross-tenant data access.
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      check: "vendor_scoping"
+
+  - id: "SVC-006"
+    name: "Service must NOT call db.commit()"
+    severity: "warning"
+    description: |
+      Services should NOT commit transactions. Transaction control belongs at the
+      API endpoint level where one request = one transaction.
+
+      This allows:
+      - Composing multiple service calls in a single transaction
+      - Clean rollback on any failure
+      - Easier testing of services in isolation
+
+      The endpoint should call db.commit() after all service operations succeed.
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      anti_patterns:
+        - "db.commit()"
+      exceptions:
+        - "log_service.py"
+
+  - id: "SVC-007"
+    name: "Service return types must match API response schemas"
+    severity: "error"
+    description: |
+      When a service method's return value will be used as an API response,
+      the returned dict keys MUST match the corresponding Pydantic schema fields.
+
+      This prevents the common bug where:
+      - Service returns {"total_imports": 5, "completed_imports": 3}
+      - Schema expects {"total": 5, "completed": 3}
+      - Frontend receives wrong/empty values
+
+      RECOMMENDED PATTERNS:
+
+      1. Return Pydantic model directly from service:
+         def get_stats(self, db: Session) -> StatsResponse:
+             return StatsResponse(total=count, completed=done)
+
+      2. Return dict with schema-matching keys:
+         def get_stats(self, db: Session) -> dict:
+             return {"total": count, "completed": done}  # Matches StatsResponse
+
+      3. Document the expected schema in service docstring:
+         def get_stats(self, db: Session) -> dict:
+             """
+             Returns dict compatible with StatsResponse schema.
+             Keys: total, pending, completed, failed
+             """
+
+      TESTING: Write tests that validate service output against schema:
+         result = service.get_stats(db)
+         StatsResponse(**result)  # Raises if keys don't match
+    pattern:
+      file_pattern: "app/services/**/*.py"
+      check: "schema_compatibility"

scripts/validate_architecture.py

@@ -122,9 +122,24 @@ class ArchitectureValidator:
         self.project_root = Path.cwd()
 
     def _load_config(self) -> dict[str, Any]:
-        """Load validation rules from YAML config"""
+        """
+        Load validation rules from YAML config.
+
+        Supports two modes:
+        1. Split directory mode: .architecture-rules/ directory with multiple YAML files
+        2. Single file mode: .architecture-rules.yaml (legacy)
+
+        The split directory mode takes precedence if it exists.
+        """
+        # Check for split directory mode first
+        rules_dir = self.config_path.parent / ".architecture-rules"
+        if rules_dir.is_dir():
+            return self._load_config_from_directory(rules_dir)
+
+        # Fall back to single file mode
         if not self.config_path.exists():
             print(f"❌ Configuration file not found: {self.config_path}")
+            print(f"   (Also checked for directory: {rules_dir})")
             sys.exit(1)
 
         with open(self.config_path) as f:
@@ -133,6 +148,44 @@ class ArchitectureValidator:
         print(f"📋 Loaded architecture rules: {config.get('project', 'unknown')}")
         return config
 
+    def _load_config_from_directory(self, rules_dir: Path) -> dict[str, Any]:
+        """
+        Load and merge configuration from split YAML files in a directory.
+
+        Reads _main.yaml first for base config, then merges all other YAML files.
+        """
+        config: dict[str, Any] = {}
+
+        # Load _main.yaml first (contains project info, principles, ignore patterns)
+        main_file = rules_dir / "_main.yaml"
+        if main_file.exists():
+            with open(main_file) as f:
+                config = yaml.safe_load(f) or {}
+
+        # Load all other YAML files and merge their contents
+        yaml_files = sorted(rules_dir.glob("*.yaml"))
+        for yaml_file in yaml_files:
+            if yaml_file.name == "_main.yaml":
+                continue  # Already loaded
+
+            with open(yaml_file) as f:
+                file_config = yaml.safe_load(f) or {}
+
+            # Merge rule sections from this file into main config
+            for key, value in file_config.items():
+                if key.endswith("_rules") and isinstance(value, list):
+                    # Merge rule lists
+                    if key not in config:
+                        config[key] = []
+                    config[key].extend(value)
+                elif key not in config:
+                    # Add new top-level keys
+                    config[key] = value
+
+        print(f"📋 Loaded architecture rules: {config.get('project', 'unknown')}")
+        print(f"   (from {len(yaml_files)} files in {rules_dir.name}/)")
+        return config
+
     def validate_all(self, target_path: Path = None) -> ValidationResult:
         """Validate all files in a directory"""
         print("\n🔍 Starting architecture validation...\n")
@@ -166,6 +219,9 @@ class ArchitectureValidator:
         # Validate templates
         self._validate_templates(target)
 
+        # Validate language/i18n rules
+        self._validate_language_rules(target)
+
         return self.result
 
     def validate_file(
@@ -1442,11 +1498,15 @@ class ArchitectureValidator:
             if "@router." in line and (
                 "post" in line or "put" in line or "delete" in line
             ):
-                # Check next 15 lines for auth or public marker
+                # Check previous line and next 15 lines for auth or public marker
                 # (increased from 5 to handle multi-line decorators and long function signatures)
                 has_auth = False
                 is_public = False
-                context_lines = lines[i - 1 : i + 15]  # Include line before decorator
+                # i is 1-indexed, lines is 0-indexed
+                # So lines[i-1] is the decorator line, lines[i-2] is the line before
+                start_idx = max(0, i - 2)  # Line before decorator (1-2 lines up)
+                end_idx = i + 15  # 15 lines after decorator
+                context_lines = lines[start_idx : end_idx]
 
                 for ctx_line in context_lines:
                     # Check for any valid auth pattern
@@ -2442,6 +2502,363 @@ class ArchitectureValidator:
                     suggestion="Add {% extends 'admin/base.html' %} at the top, or add {# standalone #} if intentional",
                 )
 
+    # =========================================================================
+    # LANGUAGE/I18N VALIDATION
+    # =========================================================================
+
+    def _validate_language_rules(self, target_path: Path):
+        """Validate language/i18n patterns"""
+        print("\n🌐 Validating language/i18n rules...")
+
+        # LANG-001: Check for invalid language codes in Python files
+        self._check_language_codes(target_path)
+
+        # LANG-002, LANG-003: Check inline Alpine.js and tojson|safe usage
+        self._check_template_language_inline_patterns(target_path)
+
+        # LANG-004: Check language selector function exists in JS files
+        self._check_language_selector_function(target_path)
+
+        # LANG-005, LANG-006, LANG-008: Check language names, flag codes, and API usage in JS files
+        self._check_language_js_patterns(target_path)
+
+        # LANG-007, LANG-009: Check language patterns in templates
+        self._check_language_template_patterns(target_path)
+
+        # LANG-010: Check translation files are valid JSON
+        self._check_translation_files(target_path)
+
+    def _check_language_codes(self, target_path: Path):
+        """LANG-001: Check for invalid language codes in Python files"""
+        py_files = list(target_path.glob("app/**/*.py"))
+        py_files.extend(list(target_path.glob("models/**/*.py")))
+
+        invalid_codes = [
+            ("'english'", "'en'"),
+            ("'french'", "'fr'"),
+            ("'german'", "'de'"),
+            ("'luxembourgish'", "'lb'"),
+            ("'lux'", "'lb'"),
+            ('"english"', '"en"'),
+            ('"french"', '"fr"'),
+            ('"german"', '"de"'),
+            ('"luxembourgish"', '"lb"'),
+            ('"lux"', '"lb"'),
+        ]
+
+        for file_path in py_files:
+            if self._should_ignore_file(file_path):
+                continue
+
+            try:
+                content = file_path.read_text()
+                lines = content.split("\n")
+
+                # Track if we're inside LANGUAGE_NAMES dicts (allowed to use language names)
+                in_language_names_dict = False
+
+                for i, line in enumerate(lines, 1):
+                    # Skip comments
+                    stripped = line.strip()
+                    if stripped.startswith("#"):
+                        continue
+
+                    # Track LANGUAGE_NAMES/LANGUAGE_NAMES_EN blocks - name values are allowed
+                    if ("LANGUAGE_NAMES" in line or "LANGUAGE_NAMES_EN" in line) and "=" in line:
+                        in_language_names_dict = True
+                    if in_language_names_dict and stripped == "}":
+                        in_language_names_dict = False
+                        continue
+                    if in_language_names_dict:
+                        continue
+
+                    for wrong, correct in invalid_codes:
+                        if wrong in line.lower():
+                            self._add_violation(
+                                rule_id="LANG-001",
+                                rule_name="Only use supported language codes",
+                                severity=Severity.ERROR,
+                                file_path=file_path,
+                                line_number=i,
+                                message=f"Invalid language code '{wrong}' - use ISO code instead",
+                                context=stripped[:80],
+                                suggestion=f"Change to: {correct}",
+                            )
+            except Exception:
+                pass  # Skip files that can't be read
+
+    def _check_template_language_inline_patterns(self, target_path: Path):
+        """LANG-002, LANG-003: Check inline Alpine.js and tojson|safe usage in templates"""
+        template_files = list(target_path.glob("app/templates/**/*.html"))
+
+        for file_path in template_files:
+            if self._should_ignore_file(file_path):
+                continue
+
+            file_path_str = str(file_path)
+
+            # Skip partials/header.html which may use hardcoded arrays (allowed)
+            if "partials/header.html" in file_path_str:
+                continue
+
+            try:
+                content = file_path.read_text()
+                lines = content.split("\n")
+
+                for i, line in enumerate(lines, 1):
+                    # LANG-002: Check for inline complex x-data with language-related properties
+                    if 'x-data="{' in line or "x-data='{" in line:
+                        # Check next few lines for language-related properties
+                        context_lines = "\n".join(lines[i - 1 : i + 10])
+                        if ("languages:" in context_lines or
+                            "languageNames:" in context_lines or
+                            "languageFlags:" in context_lines):
+                            # Check if it's using a function call (allowed)
+                            if "languageSelector(" not in context_lines:
+                                self._add_violation(
+                                    rule_id="LANG-002",
+                                    rule_name="Never use inline Alpine.js x-data for language selector",
+                                    severity=Severity.ERROR,
+                                    file_path=file_path,
+                                    line_number=i,
+                                    message="Complex language selector should use languageSelector() function",
+                                    context=line.strip()[:80],
+                                    suggestion='Use: x-data="languageSelector(\'{{ lang }}\', {{ langs|tojson|safe }})"',
+                                )
+
+                    # LANG-003: Check for tojson without safe in JavaScript context
+                    if "|tojson }}" in line and "|tojson|safe" not in line:
+                        if 'x-data=' in line:
+                            self._add_violation(
+                                rule_id="LANG-003",
+                                rule_name="Use tojson|safe for Python lists in JavaScript",
+                                severity=Severity.WARNING,
+                                file_path=file_path,
+                                line_number=i,
+                                message="tojson without |safe may cause quote escaping issues",
+                                context=line.strip()[:80],
+                                suggestion="Add |safe filter: {{ variable|tojson|safe }}",
+                            )
+            except Exception:
+                pass  # Skip files that can't be read
+
+    def _check_language_selector_function(self, target_path: Path):
+        """LANG-004: Check that languageSelector function exists and is exported"""
+        required_files = [
+            target_path / "static/shop/js/shop-layout.js",
+            target_path / "static/vendor/js/init-alpine.js",
+        ]
+
+        for file_path in required_files:
+            if not file_path.exists():
+                continue
+
+            content = file_path.read_text()
+
+            # Check for function definition
+            has_function = "function languageSelector" in content
+            has_export = "window.languageSelector" in content
+
+            if not has_function:
+                self._add_violation(
+                    rule_id="LANG-004",
+                    rule_name="Language selector function must be defined",
+                    severity=Severity.ERROR,
+                    file_path=file_path,
+                    line_number=1,
+                    message="Missing languageSelector function definition",
+                    context=file_path.name,
+                    suggestion="Add: function languageSelector(currentLang, enabledLanguages) { return {...}; }",
+                )
+
+            if has_function and not has_export:
+                self._add_violation(
+                    rule_id="LANG-004",
+                    rule_name="Language selector function must be exported",
+                    severity=Severity.ERROR,
+                    file_path=file_path,
+                    line_number=1,
+                    message="languageSelector function not exported to window",
+                    context=file_path.name,
+                    suggestion="Add: window.languageSelector = languageSelector;",
+                )
+
+    def _check_language_js_patterns(self, target_path: Path):
+        """LANG-005, LANG-006: Check language names and flag codes"""
+        js_files = list(target_path.glob("static/**/js/**/*.js"))
+
+        for file_path in js_files:
+            if self._should_ignore_file(file_path):
+                continue
+
+            content = file_path.read_text()
+            lines = content.split("\n")
+
+            for i, line in enumerate(lines, 1):
+                # Skip comments
+                stripped = line.strip()
+                if stripped.startswith("//") or stripped.startswith("/*"):
+                    continue
+
+                # LANG-005: Check for English language names instead of native
+                english_names = [
+                    ("'fr': 'French'", "'fr': 'Français'"),
+                    ("'de': 'German'", "'de': 'Deutsch'"),
+                    ("'lb': 'Luxembourgish'", "'lb': 'Lëtzebuergesch'"),
+                    ('"fr": "French"', '"fr": "Français"'),
+                    ('"de": "German"', '"de": "Deutsch"'),
+                    ('"lb": "Luxembourgish"', '"lb": "Lëtzebuergesch"'),
+                ]
+
+                for wrong, correct in english_names:
+                    if wrong.lower().replace(" ", "") in line.lower().replace(" ", ""):
+                        self._add_violation(
+                            rule_id="LANG-005",
+                            rule_name="Use native language names",
+                            severity=Severity.ERROR,
+                            file_path=file_path,
+                            line_number=i,
+                            message=f"Use native language name instead of English",
+                            context=stripped[:80],
+                            suggestion=f"Change to: {correct}",
+                        )
+
+                # LANG-006: Check for incorrect flag codes
+                wrong_flags = [
+                    ("'en': 'us'", "'en': 'gb'"),
+                    ("'en': 'en'", "'en': 'gb'"),
+                    ("'lb': 'lb'", "'lb': 'lu'"),
+                    ('"en": "us"', '"en": "gb"'),
+                    ('"en": "en"', '"en": "gb"'),
+                    ('"lb": "lb"', '"lb": "lu"'),
+                ]
+
+                for wrong, correct in wrong_flags:
+                    if wrong.lower().replace(" ", "") in line.lower().replace(" ", ""):
+                        self._add_violation(
+                            rule_id="LANG-006",
+                            rule_name="Use correct flag codes",
+                            severity=Severity.ERROR,
+                            file_path=file_path,
+                            line_number=i,
+                            message=f"Invalid flag code mapping",
+                            context=stripped[:80],
+                            suggestion=f"Change to: {correct}",
+                        )
+
+                # LANG-008: Check for wrong API method (GET instead of POST)
+                if "/language/set" in line:
+                    if "method: 'GET'" in line or 'method: "GET"' in line:
+                        self._add_violation(
+                            rule_id="LANG-008",
+                            rule_name="Language API endpoint must use POST method",
+                            severity=Severity.ERROR,
+                            file_path=file_path,
+                            line_number=i,
+                            message="Language set endpoint must use POST, not GET",
+                            context=stripped[:80],
+                            suggestion="Change to: method: 'POST'",
+                        )
+                    if "/language/set?" in line:
+                        self._add_violation(
+                            rule_id="LANG-008",
+                            rule_name="Language API endpoint must use POST method",
+                            severity=Severity.ERROR,
+                            file_path=file_path,
+                            line_number=i,
+                            message="Language set endpoint must use POST with body, not GET with query params",
+                            context=stripped[:80],
+                            suggestion="Use POST with JSON body: { language: lang }",
+                        )
+
+    def _check_language_template_patterns(self, target_path: Path):
+        """LANG-007, LANG-009: Check language patterns in templates"""
+        template_files = list(target_path.glob("app/templates/**/*.html"))
+
+        for file_path in template_files:
+            if self._should_ignore_file(file_path):
+                continue
+
+            file_path_str = str(file_path)
+            is_shop = "/shop/" in file_path_str or "\\shop\\" in file_path_str
+
+            content = file_path.read_text()
+            lines = content.split("\n")
+
+            for i, line in enumerate(lines, 1):
+                # LANG-009: Check for request.state.language without default
+                if "request.state.language" in line:
+                    # Check if it has |default
+                    if "request.state.language" in line and "|default" not in line:
+                        # Make sure it's not just part of a longer expression
+                        if re.search(r'request\.state\.language[\'"\s\}\)]', line):
+                            self._add_violation(
+                                rule_id="LANG-009",
+                                rule_name="Always provide language default",
+                                severity=Severity.ERROR,
+                                file_path=file_path,
+                                line_number=i,
+                                message="request.state.language used without default",
+                                context=line.strip()[:80],
+                                suggestion='Use: request.state.language|default("fr")',
+                            )
+
+            # LANG-007: Shop templates must use vendor.storefront_languages
+            if is_shop and "languageSelector" in content:
+                if "vendor.storefront_languages" not in content:
+                    # Check if file has any language selector
+                    if "enabled_langs" in content or "languages" in content:
+                        self._add_violation(
+                            rule_id="LANG-007",
+                            rule_name="Storefront must respect vendor languages",
+                            severity=Severity.WARNING,
+                            file_path=file_path,
+                            line_number=1,
+                            message="Shop template should use vendor.storefront_languages",
+                            context=file_path.name,
+                            suggestion="Use: {% set enabled_langs = vendor.storefront_languages if vendor else ['fr', 'de', 'en'] %}",
+                        )
+
+    def _check_translation_files(self, target_path: Path):
+        """LANG-010: Check that translation files are valid JSON"""
+        import json
+
+        locales_dir = target_path / "static/locales"
+        if not locales_dir.exists():
+            return
+
+        required_files = ["en.json", "fr.json", "de.json", "lb.json"]
+
+        for filename in required_files:
+            file_path = locales_dir / filename
+            if not file_path.exists():
+                self._add_violation(
+                    rule_id="LANG-010",
+                    rule_name="Translation files required",
+                    severity=Severity.ERROR,
+                    file_path=locales_dir,
+                    line_number=1,
+                    message=f"Missing translation file: {filename}",
+                    context=str(locales_dir),
+                    suggestion=f"Create {filename} with all required translation keys",
+                )
+                continue
+
+            try:
+                with open(file_path) as f:
+                    json.load(f)
+            except json.JSONDecodeError as e:
+                self._add_violation(
+                    rule_id="LANG-010",
+                    rule_name="Translation files must be valid JSON",
+                    severity=Severity.ERROR,
+                    file_path=file_path,
+                    line_number=e.lineno or 1,
+                    message=f"Invalid JSON: {e.msg}",
+                    context=str(e),
+                    suggestion="Fix JSON syntax error (check for trailing commas, missing quotes)",
+                )
+
     def _get_rule(self, rule_id: str) -> dict[str, Any]:
         """Get rule configuration by ID"""
         # Look in different rule categories
@@ -2453,6 +2870,7 @@ class ArchitectureValidator:
             "javascript_rules",
             "template_rules",
             "frontend_component_rules",
+            "language_rules",
         ]:
             rules = self.config.get(category, [])
             for rule in rules:

scripts/validators/__init__.py

@@ -0,0 +1,36 @@
+# scripts/validators/__init__.py
+"""
+Architecture Validators Package
+===============================
+
+This package contains domain-specific validators for the architecture validation system.
+Each validator module handles a specific category of rules.
+
+Modules:
+    - base: Base classes and helpers (Severity, Violation, ValidationResult)
+    - api_validator: API endpoint rules (API-*)
+    - service_validator: Service layer rules (SVC-*)
+    - model_validator: Model rules (MDL-*)
+    - exception_validator: Exception handling rules (EXC-*)
+    - naming_validator: Naming convention rules (NAM-*)
+    - auth_validator: Auth and multi-tenancy rules (AUTH-*, MT-*)
+    - middleware_validator: Middleware rules (MDW-*)
+    - frontend_validator: Frontend rules (JS-*, TPL-*, FE-*, CSS-*)
+    - language_validator: Language/i18n rules (LANG-*)
+"""
+
+from .base import (
+    BaseValidator,
+    FileResult,
+    Severity,
+    ValidationResult,
+    Violation,
+)
+
+__all__ = [
+    "Severity",
+    "Violation",
+    "FileResult",
+    "ValidationResult",
+    "BaseValidator",
+]

scripts/validators/base.py

@@ -0,0 +1,312 @@
+# scripts/validators/base.py
+"""
+Base classes and helpers for architecture validation.
+
+This module contains:
+- Severity: Enum for validation severity levels
+- Violation: Dataclass for representing rule violations
+- FileResult: Dataclass for single file validation results
+- ValidationResult: Dataclass for overall validation results
+- BaseValidator: Base class for domain-specific validators
+"""
+
+import json
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class Severity(Enum):
+    """Validation severity levels"""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass
+class Violation:
+    """Represents an architectural rule violation"""
+
+    rule_id: str
+    rule_name: str
+    severity: Severity
+    file_path: Path
+    line_number: int
+    message: str
+    context: str = ""
+    suggestion: str = ""
+
+
+@dataclass
+class FileResult:
+    """Results for a single file validation"""
+
+    file_path: Path
+    errors: int = 0
+    warnings: int = 0
+
+    @property
+    def passed(self) -> bool:
+        return self.errors == 0
+
+    @property
+    def status(self) -> str:
+        if self.errors > 0:
+            return "FAILED"
+        elif self.warnings > 0:
+            return "PASSED*"
+        return "PASSED"
+
+    @property
+    def status_icon(self) -> str:
+        if self.errors > 0:
+            return "❌"
+        elif self.warnings > 0:
+            return "⚠️"
+        return "✅"
+
+
+@dataclass
+class ValidationResult:
+    """Results of architecture validation"""
+
+    violations: list[Violation] = field(default_factory=list)
+    files_checked: int = 0
+    rules_applied: int = 0
+    file_results: list[FileResult] = field(default_factory=list)
+
+    def has_errors(self) -> bool:
+        """Check if there are any error-level violations"""
+        return any(v.severity == Severity.ERROR for v in self.violations)
+
+    def has_warnings(self) -> bool:
+        """Check if there are any warning-level violations"""
+        return any(v.severity == Severity.WARNING for v in self.violations)
+
+
+class BaseValidator:
+    """
+    Base class for domain-specific validators.
+
+    Provides common functionality for all validators including:
+    - Violation tracking
+    - File filtering
+    - Rule lookup
+    - Common pattern matching utilities
+    """
+
+    def __init__(
+        self,
+        config: dict[str, Any],
+        result: ValidationResult,
+        project_root: Path,
+        verbose: bool = False,
+    ):
+        """
+        Initialize validator with shared state.
+
+        Args:
+            config: Loaded architecture rules configuration
+            result: Shared ValidationResult for tracking violations
+            project_root: Root path of the project
+            verbose: Whether to show verbose output
+        """
+        self.config = config
+        self.result = result
+        self.project_root = project_root
+        self.verbose = verbose
+
+    def validate(self, target_path: Path) -> None:
+        """
+        Run validation on target path.
+
+        Must be implemented by subclasses.
+
+        Args:
+            target_path: Path to validate (file or directory)
+        """
+        raise NotImplementedError("Subclasses must implement validate()")
+
+    def _add_violation(
+        self,
+        rule_id: str,
+        rule_name: str,
+        severity: Severity,
+        file_path: Path,
+        line_number: int,
+        message: str,
+        context: str = "",
+        suggestion: str = "",
+    ) -> None:
+        """Add a violation to results"""
+        violation = Violation(
+            rule_id=rule_id,
+            rule_name=rule_name,
+            severity=severity,
+            file_path=file_path,
+            line_number=line_number,
+            message=message,
+            context=context,
+            suggestion=suggestion,
+        )
+        self.result.violations.append(violation)
+
+    def _should_ignore_file(self, file_path: Path) -> bool:
+        """Check if file should be ignored"""
+        ignore_patterns = self.config.get("ignore", {}).get("files", [])
+
+        # Convert to string for easier matching
+        file_path_str = str(file_path)
+
+        for pattern in ignore_patterns:
+            # Check if any part of the path matches the pattern
+            if file_path.match(pattern):
+                return True
+            # Also check if pattern appears in the path (for .venv, venv, etc.)
+            if "/.venv/" in file_path_str or file_path_str.startswith(".venv/"):
+                return True
+            if "/venv/" in file_path_str or file_path_str.startswith("venv/"):
+                return True
+
+        return False
+
+    def _get_rule(self, rule_id: str) -> dict[str, Any] | None:
+        """Get rule configuration by ID"""
+        # Look in different rule categories
+        for category in [
+            "api_endpoint_rules",
+            "service_layer_rules",
+            "model_rules",
+            "exception_rules",
+            "naming_rules",
+            "auth_rules",
+            "middleware_rules",
+            "javascript_rules",
+            "template_rules",
+            "frontend_component_rules",
+            "styling_rules",
+            "language_rules",
+            "multi_tenancy_rules",
+            "code_quality_rules",
+        ]:
+            rules = self.config.get(category, [])
+            for rule in rules:
+                if rule.get("id") == rule_id:
+                    return rule
+        return None
+
+    def _get_files(self, target_path: Path, pattern: str) -> list[Path]:
+        """Get files matching a glob pattern, excluding ignored files"""
+        files = list(target_path.glob(pattern))
+        return [f for f in files if not self._should_ignore_file(f)]
+
+    def _find_decorators(self, content: str) -> list[tuple[int, str, str]]:
+        """
+        Find all function decorators and their associated functions.
+
+        Returns list of (line_number, decorator, function_name) tuples.
+        """
+        results = []
+        lines = content.split("\n")
+
+        i = 0
+        while i < len(lines):
+            line = lines[i].strip()
+            if line.startswith("@"):
+                decorator = line
+                # Look for the function definition
+                for j in range(i + 1, min(i + 10, len(lines))):
+                    next_line = lines[j].strip()
+                    if next_line.startswith("def ") or next_line.startswith("async def "):
+                        # Extract function name
+                        match = re.search(r"(?:async\s+)?def\s+(\w+)", next_line)
+                        if match:
+                            func_name = match.group(1)
+                            results.append((i + 1, decorator, func_name))
+                        break
+                    elif next_line.startswith("@"):
+                        # Multiple decorators - continue to next
+                        continue
+                    elif next_line and not next_line.startswith("#"):
+                        # Non-decorator, non-comment line - stop looking
+                        break
+            i += 1
+
+        return results
+
+    def _check_pattern_in_lines(
+        self,
+        file_path: Path,
+        lines: list[str],
+        pattern: str,
+        rule_id: str,
+        rule_name: str,
+        severity: Severity,
+        message: str,
+        suggestion: str = "",
+        exclude_comments: bool = True,
+        exclude_patterns: list[str] = None,
+    ) -> None:
+        """
+        Check for pattern violations in file lines.
+
+        Args:
+            file_path: Path to the file
+            lines: File content split by lines
+            pattern: Regex pattern to search for
+            rule_id: Rule identifier
+            rule_name: Human-readable rule name
+            severity: Violation severity
+            message: Violation message
+            suggestion: Suggested fix
+            exclude_comments: Skip lines that are comments
+            exclude_patterns: Additional patterns that mark lines to skip
+        """
+        exclude_patterns = exclude_patterns or []
+
+        for i, line in enumerate(lines, 1):
+            stripped = line.strip()
+
+            # Skip comments if requested
+            if exclude_comments and stripped.startswith("#"):
+                continue
+
+            # Check exclusion patterns
+            skip = False
+            for exc in exclude_patterns:
+                if exc in line:
+                    skip = True
+                    break
+            if skip:
+                continue
+
+            # Check for pattern
+            if re.search(pattern, line):
+                self._add_violation(
+                    rule_id=rule_id,
+                    rule_name=rule_name,
+                    severity=severity,
+                    file_path=file_path,
+                    line_number=i,
+                    message=message,
+                    context=stripped[:80],
+                    suggestion=suggestion,
+                )
+
+    def _is_valid_json(self, file_path: Path) -> tuple[bool, str]:
+        """
+        Check if a file contains valid JSON.
+
+        Returns (is_valid, error_message) tuple.
+        """
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                json.load(f)
+            return True, ""
+        except json.JSONDecodeError as e:
+            return False, f"Line {e.lineno}: {e.msg}"
+        except Exception as e:
+            return False, str(e)