From 7a9dda282de2fb86e3e30ec20ba4fefec511084c Mon Sep 17 00:00:00 2001
From: Samir Boulahtit <samir.boulahtit@wizard.lu>
Date: Mon, 9 Feb 2026 21:35:53 +0100
Subject: [PATCH] refactor(scripts): reorganize scripts/ into seed/ and
 validate/ subfolders

Move 9 init/seed scripts into scripts/seed/ and 7 validation scripts
(+ validators/ subfolder) into scripts/validate/ to reduce clutter in
the root scripts/ directory. Update all references across Makefile,
CI/CD configs, pre-commit hooks, docs (~40 files), and Python imports.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .gitlab-ci.yml                                |  4 +-
 .gitlab/merge_request_templates/default.md    |  2 +-
 .performance-rules/_main.yaml                 |  2 +-
 .pre-commit-config.yaml                       |  2 +-
 .security-rules/_main.yaml                    |  2 +-
 Makefile                                      | 52 +++++++++----------
 app/modules/dev_tools/tasks/code_quality.py   |  6 +--
 docs/architecture/architecture-patterns.md    | 14 ++---
 .../architecture-violations-status.md         |  2 +-
 .../architecture/cross-module-import-rules.md |  4 +-
 docs/architecture/frontend-detection.md       |  2 +-
 docs/architecture/module-system.md            |  4 +-
 .../PLAN_storefront-module-restructure.md     |  4 +-
 ...OTE_2026-01-28_module-config-migrations.md |  2 +-
 ...2026-01-30_self-contained-module-routes.md |  2 +-
 ...2026-01-31_tenancy-module-consolidation.md |  2 +-
 docs/backend/store-in-token-architecture.md   |  8 +--
 docs/deployment/docker.md                     |  2 +-
 docs/deployment/index.md                      |  2 +-
 docs/deployment/infrastructure.md             |  2 +-
 docs/deployment/production.md                 |  2 +-
 .../development/architecture-fixes-2026-01.md |  4 +-
 docs/development/architecture-rules.md        | 20 +++----
 .../code-quality-dashboard-implementation.md  |  8 +--
 docs/development/creating-modules.md          |  4 +-
 .../database-seeder/database-init-guide.md    |  8 +--
 .../database-seeder-documentation.md          |  2 +-
 .../makefile-database-seeder.md               |  2 +-
 .../makefile-refactoring-complete.md          | 16 +++---
 .../module-autodiscovery-migration.md         |  6 +--
 .../migration/svc-006-migration-plan.md       | 10 ++--
 docs/development/performance-rules.md         | 14 ++---
 docs/development/security-rules.md            | 14 ++---
 docs/development/seed-scripts-audit.md        | 10 ++--
 docs/features/cms-implementation-guide.md     |  4 +-
 docs/features/content-management-system.md    |  2 +-
 docs/features/email-system.md                 |  4 +-
 docs/features/platform-homepage.md            |  4 +-
 .../platform-homepage-quick-start.md          |  4 +-
 docs/implementation/email-settings.md         |  2 +-
 .../email-templates-architecture.md           |  4 +-
 ..._2026-02-09_import002-cross-module-deps.md |  4 +-
 .../decouple-modules-implementation-plan.md   |  2 +-
 docs/proposals/plan-perms.md                  |  2 +-
 scripts/README.md                             | 14 ++---
 scripts/{ => seed}/backup_database.py         |  0
 .../create_default_content_pages.py           |  0
 scripts/{ => seed}/create_platform_pages.py   |  0
 scripts/{ => seed}/init_db.py                 |  0
 scripts/{ => seed}/init_log_settings.py       |  0
 scripts/{ => seed}/init_production.py         |  0
 scripts/{ => seed}/install.py                 |  0
 scripts/{ => seed}/seed_demo.py               |  0
 scripts/{ => seed}/seed_email_templates.py    |  0
 scripts/{ => validate}/base_validator.py      |  0
 scripts/{ => validate}/validate_all.py        | 19 ++++---
 .../{ => validate}/validate_architecture.py   | 12 ++---
 scripts/{ => validate}/validate_audit.py      |  6 +--
 .../{ => validate}/validate_performance.py    | 12 ++---
 scripts/{ => validate}/validate_security.py   | 12 ++---
 scripts/{ => validate}/validators/__init__.py |  0
 scripts/{ => validate}/validators/base.py     |  0
 .../{ => validate}/verify_critical_imports.py |  0
 63 files changed, 173 insertions(+), 174 deletions(-)
 rename scripts/{ => seed}/backup_database.py (100%)
 rename scripts/{ => seed}/create_default_content_pages.py (100%)
 rename scripts/{ => seed}/create_platform_pages.py (100%)
 rename scripts/{ => seed}/init_db.py (100%)
 rename scripts/{ => seed}/init_log_settings.py (100%)
 rename scripts/{ => seed}/init_production.py (100%)
 rename scripts/{ => seed}/install.py (100%)
 rename scripts/{ => seed}/seed_demo.py (100%)
 rename scripts/{ => seed}/seed_email_templates.py (100%)
 rename scripts/{ => validate}/base_validator.py (100%)
 rename scripts/{ => validate}/validate_all.py (91%)
 rename scripts/{ => validate}/validate_architecture.py (99%)
 rename scripts/{ => validate}/validate_audit.py (99%)
 rename scripts/{ => validate}/validate_performance.py (98%)
 rename scripts/{ => validate}/validate_security.py (98%)
 rename scripts/{ => validate}/validators/__init__.py (100%)
 rename scripts/{ => validate}/validators/base.py (100%)
 rename scripts/{ => validate}/verify_critical_imports.py (100%)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 93ae001f..3680f562 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -79,7 +79,7 @@ architecture:
     - pip install uv
     - uv sync --frozen
   script:
-    - .venv/bin/python scripts/validate_architecture.py
+    - .venv/bin/python scripts/validate/validate_architecture.py
   rules:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
@@ -106,7 +106,7 @@ audit:
     - pip install uv
     - uv sync --frozen
   script:
-    - .venv/bin/python scripts/validate_audit.py
+    - .venv/bin/python scripts/validate/validate_audit.py
   allow_failure: true
   rules:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
diff --git a/.gitlab/merge_request_templates/default.md b/.gitlab/merge_request_templates/default.md
index e4b7d3ee..fc9ecd44 100644
--- a/.gitlab/merge_request_templates/default.md
+++ b/.gitlab/merge_request_templates/default.md
@@ -20,7 +20,7 @@
 
 <!-- Describe how you tested these changes -->
 - [ ] Unit tests pass (`pytest tests/`)
-- [ ] Architecture validation passes (`python scripts/validate_architecture.py`)
+- [ ] Architecture validation passes (`python scripts/validate/validate_architecture.py`)
 - [ ] Manual testing performed
 
 ## Checklist
diff --git a/.performance-rules/_main.yaml b/.performance-rules/_main.yaml
index abad34f7..0aea096b 100644
--- a/.performance-rules/_main.yaml
+++ b/.performance-rules/_main.yaml
@@ -1,7 +1,7 @@
 # Performance Rules Configuration
 # ================================
 # Performance-focused validation rules for the codebase.
-# Run with: python scripts/validate_performance.py
+# Run with: python scripts/validate/validate_performance.py
 
 version: "1.0"
 project: "letzshop-product-import"
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index eadb04d0..ac198a26 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -9,7 +9,7 @@ repos:
     hooks:
       - id: validate-architecture
         name: Validate Architecture Patterns
-        entry: python scripts/validate_architecture.py
+        entry: python scripts/validate/validate_architecture.py
         language: python
         pass_filenames: false
         always_run: true
diff --git a/.security-rules/_main.yaml b/.security-rules/_main.yaml
index 8b8ea1e4..070b035b 100644
--- a/.security-rules/_main.yaml
+++ b/.security-rules/_main.yaml
@@ -1,7 +1,7 @@
 # Security Rules Configuration
 # ============================
 # Security-focused validation rules for the codebase.
-# Run with: python scripts/validate_security.py
+# Run with: python scripts/validate/validate_security.py
 
 version: "1.0"
 project: "letzshop-product-import"
diff --git a/Makefile b/Makefile
index 280ec03b..2872959e 100644
--- a/Makefile
+++ b/Makefile
@@ -105,19 +105,19 @@ init-prod:
 	@$(PYTHON) -m alembic upgrade heads
 	@echo ""
 	@echo "Step 1/6: Creating admin user and platform settings..."
-	$(PYTHON) scripts/init_production.py
+	$(PYTHON) scripts/seed/init_production.py
 	@echo ""
 	@echo "Step 2/6: Initializing log settings..."
-	$(PYTHON) scripts/init_log_settings.py
+	$(PYTHON) scripts/seed/init_log_settings.py
 	@echo ""
 	@echo "Step 3/6: Creating default CMS content pages..."
-	$(PYTHON) scripts/create_default_content_pages.py
+	$(PYTHON) scripts/seed/create_default_content_pages.py
 	@echo ""
 	@echo "Step 4/6: Creating platform pages and landing..."
-	$(PYTHON) scripts/create_platform_pages.py
+	$(PYTHON) scripts/seed/create_platform_pages.py
 	@echo ""
 	@echo "Step 5/6: Seeding email templates..."
-	$(PYTHON) scripts/seed_email_templates.py
+	$(PYTHON) scripts/seed/seed_email_templates.py
 	@echo ""
 	@echo "Step 6/6: Seeding subscription tiers..."
 	@echo "  (Handled by init_production.py Step 6)"
@@ -127,40 +127,40 @@ init-prod:
 
 seed-tiers:
 	@echo "🏷️  Seeding subscription tiers..."
-	$(PYTHON) -c "from scripts.init_production import *; from app.core.database import SessionLocal; from sqlalchemy import select; db = SessionLocal(); oms = db.execute(select(Platform).where(Platform.code == 'oms')).scalar_one_or_none(); create_subscription_tiers(db, oms) if oms else print('OMS platform not found'); db.commit(); db.close()"
+	$(PYTHON) -c "from scripts.seed.init_production import *; from app.core.database import SessionLocal; from sqlalchemy import select; db = SessionLocal(); oms = db.execute(select(Platform).where(Platform.code == 'oms')).scalar_one_or_none(); create_subscription_tiers(db, oms) if oms else print('OMS platform not found'); db.commit(); db.close()"
 	@echo "✅ Subscription tiers seeded"
 
 # First-time installation - Complete setup with configuration validation
 platform-install:
 	@echo "🚀 WIZAMART PLATFORM INSTALLATION"
 	@echo "=================================="
-	$(PYTHON) scripts/install.py
+	$(PYTHON) scripts/seed/install.py
 
 # Demo data seeding - Cross-platform using Python to set environment
 seed-demo:
 	@echo "🎪 Seeding demo data (normal mode)..."
 ifeq ($(DETECTED_OS),Windows)
-	@set SEED_MODE=normal&& $(PYTHON) scripts/seed_demo.py
+	@set SEED_MODE=normal&& $(PYTHON) scripts/seed/seed_demo.py
 else
-	SEED_MODE=normal $(PYTHON) scripts/seed_demo.py
+	SEED_MODE=normal $(PYTHON) scripts/seed/seed_demo.py
 endif
 	@echo "✅ Demo seeding completed"
 
 seed-demo-minimal:
 	@echo "🎪 Seeding demo data (minimal mode - 1 store only)..."
 ifeq ($(DETECTED_OS),Windows)
-	@set SEED_MODE=minimal&& $(PYTHON) scripts/seed_demo.py
+	@set SEED_MODE=minimal&& $(PYTHON) scripts/seed/seed_demo.py
 else
-	SEED_MODE=minimal $(PYTHON) scripts/seed_demo.py
+	SEED_MODE=minimal $(PYTHON) scripts/seed/seed_demo.py
 endif
 	@echo "✅ Minimal demo seeding completed"
 
 seed-demo-reset:
 	@echo "⚠️  WARNING: This will DELETE ALL existing data!"
 ifeq ($(DETECTED_OS),Windows)
-	@set SEED_MODE=reset&& $(PYTHON) scripts/seed_demo.py
+	@set SEED_MODE=reset&& $(PYTHON) scripts/seed/seed_demo.py
 else
-	SEED_MODE=reset $(PYTHON) scripts/seed_demo.py
+	SEED_MODE=reset $(PYTHON) scripts/seed/seed_demo.py
 endif
 
 db-setup: migrate-up init-prod seed-demo
@@ -175,34 +175,34 @@ db-reset:
 	@echo "Applying all migrations..."
 	$(PYTHON) -m alembic upgrade head
 	@echo "Initializing production data..."
-	$(PYTHON) scripts/init_production.py
+	$(PYTHON) scripts/seed/init_production.py
 	@echo "Seeding demo data..."
 ifeq ($(DETECTED_OS),Windows)
-	@set SEED_MODE=reset&& set FORCE_RESET=true&& $(PYTHON) scripts/seed_demo.py
+	@set SEED_MODE=reset&& set FORCE_RESET=true&& $(PYTHON) scripts/seed/seed_demo.py
 else
-	SEED_MODE=reset FORCE_RESET=true $(PYTHON) scripts/seed_demo.py
+	SEED_MODE=reset FORCE_RESET=true $(PYTHON) scripts/seed/seed_demo.py
 endif
 	@echo ""
 	@echo "✅ Database completely reset!"
 
 backup-db:
 	@echo "Creating database backup..."
-	@$(PYTHON) scripts/backup_database.py
+	@$(PYTHON) scripts/seed/backup_database.py
 
 # Utility commands (usually not needed - init-prod handles these)
 create-cms-defaults:
 	@echo "📄 Creating default CMS content pages..."
-	$(PYTHON) scripts/create_default_content_pages.py
+	$(PYTHON) scripts/seed/create_default_content_pages.py
 	@echo "✅ CMS defaults created"
 
 create-platform-pages:
 	@echo "🏠 Creating platform pages and landing..."
-	$(PYTHON) scripts/create_platform_pages.py
+	$(PYTHON) scripts/seed/create_platform_pages.py
 	@echo "✅ Platform pages created"
 
 init-logging:
 	@echo "📝 Initializing log settings..."
-	$(PYTHON) scripts/init_log_settings.py
+	$(PYTHON) scripts/seed/init_log_settings.py
 	@echo "✅ Log settings initialized"
 
 # =============================================================================
@@ -325,31 +325,31 @@ ci: lint-strict verify-imports test-coverage
 
 verify-imports:
 	@echo "Verifying critical imports..."
-	$(PYTHON) scripts/verify_critical_imports.py
+	$(PYTHON) scripts/validate/verify_critical_imports.py
 
 arch-check:
 	@echo "Running architecture validation..."
-	$(PYTHON) scripts/validate_architecture.py
+	$(PYTHON) scripts/validate/validate_architecture.py
 
 arch-check-file:
 ifeq ($(DETECTED_OS),Windows)
-	@if "$(file)"=="" (echo Error: Please provide a file. Usage: make arch-check-file file="path/to/file.py") else ($(PYTHON) scripts/validate_architecture.py -f "$(file)")
+	@if "$(file)"=="" (echo Error: Please provide a file. Usage: make arch-check-file file="path/to/file.py") else ($(PYTHON) scripts/validate/validate_architecture.py -f "$(file)")
 else
 	@if [ -z "$(file)" ]; then \
 		echo "Error: Please provide a file. Usage: make arch-check-file file=\"path/to/file.py\""; \
 	else \
-		$(PYTHON) scripts/validate_architecture.py -f "$(file)"; \
+		$(PYTHON) scripts/validate/validate_architecture.py -f "$(file)"; \
 	fi
 endif
 
 arch-check-object:
 ifeq ($(DETECTED_OS),Windows)
-	@if "$(name)"=="" (echo Error: Please provide an object name. Usage: make arch-check-object name="merchant") else ($(PYTHON) scripts/validate_architecture.py -o "$(name)")
+	@if "$(name)"=="" (echo Error: Please provide an object name. Usage: make arch-check-object name="merchant") else ($(PYTHON) scripts/validate/validate_architecture.py -o "$(name)")
 else
 	@if [ -z "$(name)" ]; then \
 		echo "Error: Please provide an object name. Usage: make arch-check-object name=\"merchant\""; \
 	else \
-		$(PYTHON) scripts/validate_architecture.py -o "$(name)"; \
+		$(PYTHON) scripts/validate/validate_architecture.py -o "$(name)"; \
 	fi
 endif
 
diff --git a/app/modules/dev_tools/tasks/code_quality.py b/app/modules/dev_tools/tasks/code_quality.py
index 2f835511..aa3b1b7b 100644
--- a/app/modules/dev_tools/tasks/code_quality.py
+++ b/app/modules/dev_tools/tasks/code_quality.py
@@ -28,9 +28,9 @@ VALID_VALIDATOR_TYPES = [VALIDATOR_ARCHITECTURE, VALIDATOR_SECURITY, VALIDATOR_P
 
 # Map validator types to their scripts
 VALIDATOR_SCRIPTS = {
-    VALIDATOR_ARCHITECTURE: "scripts/validate_architecture.py",
-    VALIDATOR_SECURITY: "scripts/validate_security.py",
-    VALIDATOR_PERFORMANCE: "scripts/validate_performance.py",
+    VALIDATOR_ARCHITECTURE: "scripts/validate/validate_architecture.py",
+    VALIDATOR_SECURITY: "scripts/validate/validate_security.py",
+    VALIDATOR_PERFORMANCE: "scripts/validate/validate_performance.py",
 }
 
 # Human-readable names
diff --git a/docs/architecture/architecture-patterns.md b/docs/architecture/architecture-patterns.md
index 49ab80c6..786b2e04 100644
--- a/docs/architecture/architecture-patterns.md
+++ b/docs/architecture/architecture-patterns.md
@@ -2,7 +2,7 @@
 
 This document describes the architectural patterns and design decisions that must be followed throughout the codebase.
 
-> **Note:** These patterns are enforced automatically by `scripts/validate_architecture.py`. Run the validator before committing code.
+> **Note:** These patterns are enforced automatically by `scripts/validate/validate_architecture.py`. Run the validator before committing code.
 
 ---
 
@@ -609,16 +609,16 @@ function storesManager() {
 
 ```bash
 # Validate entire codebase
-python scripts/validate_architecture.py
+python scripts/validate/validate_architecture.py
 
 # Validate specific directory
-python scripts/validate_architecture.py app/api/
+python scripts/validate/validate_architecture.py app/api/
 
 # Verbose output with context
-python scripts/validate_architecture.py --verbose
+python scripts/validate/validate_architecture.py --verbose
 
 # Errors only (suppress warnings)
-python scripts/validate_architecture.py --errors-only
+python scripts/validate/validate_architecture.py --errors-only
 ```
 
 ### Pre-commit Hook
@@ -644,7 +644,7 @@ Add to your CI pipeline:
 # .github/workflows/ci.yml
 - name: Validate Architecture
   run: |
-    python scripts/validate_architecture.py
+    python scripts/validate/validate_architecture.py
 ```
 
 ---
@@ -703,4 +703,4 @@ class StoreService:
 
 ---
 
-**Remember:** These patterns are enforced automatically. Run `python scripts/validate_architecture.py` before committing!
+**Remember:** These patterns are enforced automatically. Run `python scripts/validate/validate_architecture.py` before committing!
diff --git a/docs/architecture/architecture-violations-status.md b/docs/architecture/architecture-violations-status.md
index 9cf0a2dc..1023d599 100644
--- a/docs/architecture/architecture-violations-status.md
+++ b/docs/architecture/architecture-violations-status.md
@@ -153,7 +153,7 @@ async def update_merchant_endpoint(merchant_id: int, data: MerchantUpdate, db: S
 ## Validation Command
 
 ```bash
-python scripts/validate_architecture.py
+python scripts/validate/validate_architecture.py
 ```
 
 ## Next Actions
diff --git a/docs/architecture/cross-module-import-rules.md b/docs/architecture/cross-module-import-rules.md
index d794d8ba..9c27af07 100644
--- a/docs/architecture/cross-module-import-rules.md
+++ b/docs/architecture/cross-module-import-rules.md
@@ -183,7 +183,7 @@ def get_module_if_enabled(db, platform_id, module_code):
 
 ## Architecture Validation
 
-The architecture validator (`scripts/validate_architecture.py`) includes rules to detect violations:
+The architecture validator (`scripts/validate/validate_architecture.py`) includes rules to detect violations:
 
 | Rule | Severity | Description |
 |------|----------|-------------|
@@ -193,7 +193,7 @@ The architecture validator (`scripts/validate_architecture.py`) includes rules t
 
 Run validation:
 ```bash
-python scripts/validate_architecture.py
+python scripts/validate/validate_architecture.py
 ```
 
 ## Provider Pattern Summary
diff --git a/docs/architecture/frontend-detection.md b/docs/architecture/frontend-detection.md
index 2045d418..037df9b7 100644
--- a/docs/architecture/frontend-detection.md
+++ b/docs/architecture/frontend-detection.md
@@ -262,7 +262,7 @@ pytest tests/unit/core/test_frontend_detector.py tests/unit/middleware/test_fron
 
 ## Architecture Rules
 
-These rules are enforced by `scripts/validate_architecture.py`:
+These rules are enforced by `scripts/validate/validate_architecture.py`:
 
 | Rule | Description |
 |------|-------------|
diff --git a/docs/architecture/module-system.md b/docs/architecture/module-system.md
index 43eb5abe..2d54df46 100644
--- a/docs/architecture/module-system.md
+++ b/docs/architecture/module-system.md
@@ -1216,7 +1216,7 @@ MARKETPLACE_BATCH_SIZE=500
 
 ## Architecture Validation Rules
 
-The architecture validator (`scripts/validate_architecture.py`) enforces module structure:
+The architecture validator (`scripts/validate/validate_architecture.py`) enforces module structure:
 
 | Rule | Severity | Description |
 |------|----------|-------------|
@@ -1246,7 +1246,7 @@ The architecture validator (`scripts/validate_architecture.py`) enforces module
 
 Run validation:
 ```bash
-python scripts/validate_architecture.py
+python scripts/validate/validate_architecture.py
 ```
 
 ## Best Practices
diff --git a/docs/archive/PLAN_storefront-module-restructure.md b/docs/archive/PLAN_storefront-module-restructure.md
index e25ae468..37fe5edd 100644
--- a/docs/archive/PLAN_storefront-module-restructure.md
+++ b/docs/archive/PLAN_storefront-module-restructure.md
@@ -47,7 +47,7 @@ Add new rule:
 
 ### Task 1.2: Update validator to check this rule
 
-**File:** `scripts/validate_architecture.py`
+**File:** `scripts/validate/validate_architecture.py`
 
 Add validation for API-007.
 
@@ -340,5 +340,5 @@ After migrated to `app/modules/cart/services/cart_service.py`.
 
 ### Modified Files
 - `app/api/deps.py` (CustomerContext return type)
-- `scripts/validate_architecture.py` (add API-007 check)
+- `scripts/validate/validate_architecture.py` (add API-007 check)
 - All files currently importing from legacy locations
diff --git a/docs/archive/SESSION_NOTE_2026-01-28_module-config-migrations.md b/docs/archive/SESSION_NOTE_2026-01-28_module-config-migrations.md
index 759fcbb9..7d343173 100644
--- a/docs/archive/SESSION_NOTE_2026-01-28_module-config-migrations.md
+++ b/docs/archive/SESSION_NOTE_2026-01-28_module-config-migrations.md
@@ -101,7 +101,7 @@ Committed all pending module migration work:
 Run architecture validator and fix all modules to comply with rules:
 
 ```bash
-python scripts/validate_architecture.py
+python scripts/validate/validate_architecture.py
 ```
 
 Check each module for:
diff --git a/docs/archive/SESSION_NOTE_2026-01-30_self-contained-module-routes.md b/docs/archive/SESSION_NOTE_2026-01-30_self-contained-module-routes.md
index 38989f0c..07f08d57 100644
--- a/docs/archive/SESSION_NOTE_2026-01-30_self-contained-module-routes.md
+++ b/docs/archive/SESSION_NOTE_2026-01-30_self-contained-module-routes.md
@@ -246,7 +246,7 @@ router.include_router({module}_admin_router, tags=["admin-{module}"])
 ## Validation
 
 After each module migration:
-1. Run `python scripts/validate_architecture.py`
+1. Run `python scripts/validate/validate_architecture.py`
 2. Test affected endpoints manually
 3. Verify imports work: `python -c "from app.api.v1.admin import router"`
 
diff --git a/docs/archive/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md b/docs/archive/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md
index 6c3da775..ce996542 100644
--- a/docs/archive/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md
+++ b/docs/archive/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md
@@ -142,4 +142,4 @@ Added new rules to enforce module-first architecture:
 - `/docs/architecture/module-system.md`
 - `/docs/development/migration/module-autodiscovery-migration.md`
 - `/.architecture-rules/module.yaml`
-- `/scripts/validate_architecture.py`
+- `/scripts/validate/validate_architecture.py`
diff --git a/docs/backend/store-in-token-architecture.md b/docs/backend/store-in-token-architecture.md
index 71dafed2..63b3afdb 100644
--- a/docs/backend/store-in-token-architecture.md
+++ b/docs/backend/store-in-token-architecture.md
@@ -525,7 +525,7 @@ The architecture enforces a strict layered pattern for where exceptions should b
 
 ### Enforced by Architecture Validation
 
-The validation script (`scripts/validate_architecture.py`) enforces these rules:
+The validation script (`scripts/validate/validate_architecture.py`) enforces these rules:
 
 **Rule API-003: Endpoints must NOT raise exceptions directly**
 - Detects `raise HTTPException`, `raise InvalidTokenException`, etc. in endpoint files
@@ -542,7 +542,7 @@ Architecture validation runs on every commit:
   hooks:
     - id: validate-architecture
       name: Validate Architecture Patterns
-      entry: python scripts/validate_architecture.py
+      entry: python scripts/validate/validate_architecture.py
       language: python
       pass_filenames: false
       always_run: true
@@ -550,8 +550,8 @@ Architecture validation runs on every commit:
 
 To run manually:
 ```bash
-python scripts/validate_architecture.py  # Full validation
-python scripts/validate_architecture.py -d app/api/v1/store/  # Specific directory
+python scripts/validate/validate_architecture.py  # Full validation
+python scripts/validate/validate_architecture.py -d app/api/v1/store/  # Specific directory
 ```
 
 See `.architecture-rules.yaml` for the complete rule definitions.
diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md
index 1fc64d7c..e021f1c9 100644
--- a/docs/deployment/docker.md
+++ b/docs/deployment/docker.md
@@ -291,7 +291,7 @@ docker compose -f docker-compose.prod.yml up -d
 docker compose -f docker-compose.prod.yml exec api alembic upgrade head
 
 # Initialize data
-docker compose -f docker-compose.prod.yml exec api python scripts/init_production.py
+docker compose -f docker-compose.prod.yml exec api python scripts/seed/init_production.py
 ```
 
 ---
diff --git a/docs/deployment/index.md b/docs/deployment/index.md
index 50c08fe0..f5909ae3 100644
--- a/docs/deployment/index.md
+++ b/docs/deployment/index.md
@@ -85,7 +85,7 @@ source .venv/bin/activate
 alembic upgrade head
 
 # Initialize production data
-python scripts/init_production.py
+python scripts/seed/init_production.py
 ```
 
 ### 3. Static Assets
diff --git a/docs/deployment/infrastructure.md b/docs/deployment/infrastructure.md
index 75e7071f..90fb145c 100644
--- a/docs/deployment/infrastructure.md
+++ b/docs/deployment/infrastructure.md
@@ -248,7 +248,7 @@ nano .env  # Edit with production values
 sudo -u postgres createuser wizamart_user
 sudo -u postgres createdb wizamart_db -O wizamart_user
 alembic upgrade head
-python scripts/init_production.py
+python scripts/seed/init_production.py
 
 # 6. Create systemd service
 sudo nano /etc/systemd/system/wizamart.service
diff --git a/docs/deployment/production.md b/docs/deployment/production.md
index 7d5c209c..4e77af82 100644
--- a/docs/deployment/production.md
+++ b/docs/deployment/production.md
@@ -44,7 +44,7 @@ nano .env  # Edit with production values
 
 # 6. Initialize database
 alembic upgrade head
-python scripts/init_production.py
+python scripts/seed/init_production.py
 
 # 7. Exit wizamart user
 exit
diff --git a/docs/development/architecture-fixes-2026-01.md b/docs/development/architecture-fixes-2026-01.md
index 52efce35..b98937c4 100644
--- a/docs/development/architecture-fixes-2026-01.md
+++ b/docs/development/architecture-fixes-2026-01.md
@@ -409,7 +409,7 @@ language: '{{ request.state.language|default("fr") }}'
 
 ### 6.1 LANG-001 False Positive
 
-**File:** `scripts/validate_architecture.py`
+**File:** `scripts/validate/validate_architecture.py`
 
 **Problem:** Validator flagged "English" as invalid language code in `SUPPORTED_LANGUAGES` dict (where it's a display name, not a code).
 
@@ -456,7 +456,7 @@ if in_language_names_block and stripped in ("}", "]"):
 After these changes:
 
 ```bash
-$ python scripts/validate_architecture.py
+$ python scripts/validate/validate_architecture.py
 
 Files checked: 439
 Findings: 0 errors, 141 warnings, 2 info
diff --git a/docs/development/architecture-rules.md b/docs/development/architecture-rules.md
index 1a721786..aae3eb02 100644
--- a/docs/development/architecture-rules.md
+++ b/docs/development/architecture-rules.md
@@ -1,6 +1,6 @@
 # Architecture Rules Reference
 
-This document provides a comprehensive reference for all architectural rules enforced by the `scripts/validate_architecture.py` validator.
+This document provides a comprehensive reference for all architectural rules enforced by the `scripts/validate/validate_architecture.py` validator.
 
 ## Overview
 
@@ -33,23 +33,23 @@ make qa
 
 ```bash
 # Check all files
-python scripts/validate_architecture.py
+python scripts/validate/validate_architecture.py
 
 # Check specific directory
-python scripts/validate_architecture.py -d app/api/
+python scripts/validate/validate_architecture.py -d app/api/
 
 # Check a single file
-python scripts/validate_architecture.py -f app/api/v1/admin/stores.py
+python scripts/validate/validate_architecture.py -f app/api/v1/admin/stores.py
 
 # Check all files for an entity
-python scripts/validate_architecture.py -o merchant
-python scripts/validate_architecture.py -o store
+python scripts/validate/validate_architecture.py -o merchant
+python scripts/validate/validate_architecture.py -o store
 
 # Verbose output
-python scripts/validate_architecture.py --verbose
+python scripts/validate/validate_architecture.py --verbose
 
 # JSON output (for CI/CD)
-python scripts/validate_architecture.py --json
+python scripts/validate/validate_architecture.py --json
 ```
 
 ### Output Format
@@ -1072,7 +1072,7 @@ Before committing code:
 
 - [ ] Run `make format` (Ruff formatting)
 - [ ] Run `make lint` (Ruff + mypy)
-- [ ] Run `python scripts/validate_architecture.py`
+- [ ] Run `python scripts/validate/validate_architecture.py`
 - [ ] Fix all **Error** level violations
 - [ ] Review **Warning** level violations
 - [ ] Run relevant tests
@@ -1099,7 +1099,7 @@ Before committing code:
 All rules are defined in `.architecture-rules.yaml`. To modify rules:
 
 1. Edit `.architecture-rules.yaml`
-2. Update `scripts/validate_architecture.py` if implementing new checks
+2. Update `scripts/validate/validate_architecture.py` if implementing new checks
 3. Run validator to test changes
 4. Update this documentation
 
diff --git a/docs/development/code-quality-dashboard-implementation.md b/docs/development/code-quality-dashboard-implementation.md
index 092f8459..a3bd89dd 100644
--- a/docs/development/code-quality-dashboard-implementation.md
+++ b/docs/development/code-quality-dashboard-implementation.md
@@ -8,7 +8,7 @@ This document tracks the implementation of the Code Quality Dashboard for tracki
 
 ## Overview
 
-The Code Quality Dashboard provides a UI for viewing, managing, and tracking architecture violations detected by `scripts/validate_architecture.py`. This allows teams to:
+The Code Quality Dashboard provides a UI for viewing, managing, and tracking architecture violations detected by `scripts/validate/validate_architecture.py`. This allows teams to:
 
 - View violations in a user-friendly interface
 - Track technical debt over time
@@ -90,7 +90,7 @@ class CodeQualityService:
         Run architecture validator and store results
 
         Steps:
-        1. Execute scripts/validate_architecture.py
+        1. Execute scripts/validate/validate_architecture.py
         2. Parse JSON output
         3. Create ArchitectureScan record
         4. Create ArchitectureViolation records
@@ -216,7 +216,7 @@ def run_scan(db: Session, triggered_by: str = 'manual') -> ArchitectureScan:
     # Run validator
     start_time = datetime.now()
     result = subprocess.run(
-        ['python', 'scripts/validate_architecture.py', '--json'],
+        ['python', 'scripts/validate/validate_architecture.py', '--json'],
         capture_output=True,
         text=True
     )
@@ -563,7 +563,7 @@ function codeQualityDashboard() {
 
 ## Validator Output Format
 
-**Update:** `scripts/validate_architecture.py`
+**Update:** `scripts/validate/validate_architecture.py`
 
 Add JSON output support:
 
diff --git a/docs/development/creating-modules.md b/docs/development/creating-modules.md
index 8a1888da..dcbbfaf6 100644
--- a/docs/development/creating-modules.md
+++ b/docs/development/creating-modules.md
@@ -501,7 +501,7 @@ Existing modules (CMS, billing, marketplace, etc.) currently have their migratio
 Run the architecture validator to check your module:
 
 ```bash
-python scripts/validate_architecture.py
+python scripts/validate/validate_architecture.py
 ```
 
 ### Validation Rules
@@ -538,7 +538,7 @@ python scripts/validate_architecture.py
 - [ ] Create locales (en, de, fr, lu)
 - [ ] Create `config.py` if module needs environment settings (optional)
 - [ ] Create `migrations/versions/` with `__init__.py` files if module has database tables
-- [ ] Run `python scripts/validate_architecture.py`
+- [ ] Run `python scripts/validate/validate_architecture.py`
 - [ ] Test routes are accessible
 
 ### No Framework Changes Needed
diff --git a/docs/development/database-seeder/database-init-guide.md b/docs/development/database-seeder/database-init-guide.md
index e50d57e8..12e07e77 100644
--- a/docs/development/database-seeder/database-init-guide.md
+++ b/docs/development/database-seeder/database-init-guide.md
@@ -368,7 +368,7 @@ make help-db
 
 ### Adding New Admin Settings
 
-Edit `scripts/init_production.py` to add new platform settings:
+Edit `scripts/seed/init_production.py` to add new platform settings:
 
 ```python
 def create_admin_settings(db: Session) -> int:
@@ -391,7 +391,7 @@ def create_admin_settings(db: Session) -> int:
 
 ### Adding New Demo Data
 
-Edit `scripts/seed_demo.py` to extend demo data creation:
+Edit `scripts/seed/seed_demo.py` to extend demo data creation:
 
 ```python
 def seed_demo_data(db: Session, auth_manager: AuthManager):
@@ -468,7 +468,7 @@ if settings.your_boolean_setting:
 
 ### Adding New Demo Store Configurations
 
-Edit the `DEMO_STORES` list in `scripts/seed_demo.py`:
+Edit the `DEMO_STORES` list in `scripts/seed/seed_demo.py`:
 
 ```python
 DEMO_STORES = [
@@ -507,7 +507,7 @@ Add corresponding Makefile command:
 ```makefile
 seed-demo-custom:
 	@echo 🎪 Seeding custom demo data...
-	@set SEED_MODE=custom&& $(PYTHON) scripts/seed_demo.py
+	@set SEED_MODE=custom&& $(PYTHON) scripts/seed/seed_demo.py
 	@echo ✅ Custom demo seeding completed
 ```
 
diff --git a/docs/development/database-seeder/database-seeder-documentation.md b/docs/development/database-seeder/database-seeder-documentation.md
index 6911531d..7f9a3766 100644
--- a/docs/development/database-seeder/database-seeder-documentation.md
+++ b/docs/development/database-seeder/database-seeder-documentation.md
@@ -364,7 +364,7 @@ To create platform-level default content pages (About, Contact, FAQ, Shipping, R
 ```bash
 make create-cms-defaults
 # or
-python scripts/create_default_content_pages.py
+python scripts/seed/create_default_content_pages.py
 ```
 
 This creates 7 platform default pages that all stores inherit:
diff --git a/docs/development/database-seeder/makefile-database-seeder.md b/docs/development/database-seeder/makefile-database-seeder.md
index c644ce6b..52a980f0 100644
--- a/docs/development/database-seeder/makefile-database-seeder.md
+++ b/docs/development/database-seeder/makefile-database-seeder.md
@@ -171,7 +171,7 @@ migrate-status:
 
 backup-db:
 	@echo Creating database backup...
-	@$(PYTHON) scripts/backup_database.py
+	@$(PYTHON) scripts/seed/backup_database.py
 
 seed:
 	@echo Seeding database with comprehensive test data...
diff --git a/docs/development/migration/makefile-refactoring-complete.md b/docs/development/migration/makefile-refactoring-complete.md
index e599c498..272a6df6 100644
--- a/docs/development/migration/makefile-refactoring-complete.md
+++ b/docs/development/migration/makefile-refactoring-complete.md
@@ -34,7 +34,7 @@ Successfully refactored the Makefile to establish clear separation between **pro
 **Before:**
 ```makefile
 init-prod:
-	$(PYTHON) scripts/init_production.py
+	$(PYTHON) scripts/seed/init_production.py
 ```
 
 **After:**
@@ -42,13 +42,13 @@ init-prod:
 init-prod:
 	@echo "🔧 Initializing production database..."
 	@echo "Step 1/4: Creating admin user and platform alerts..."
-	$(PYTHON) scripts/init_production.py
+	$(PYTHON) scripts/seed/init_production.py
 	@echo "Step 2/4: Initializing log settings..."
-	$(PYTHON) scripts/init_log_settings.py
+	$(PYTHON) scripts/seed/init_log_settings.py
 	@echo "Step 3/4: Creating default CMS content pages..."
-	$(PYTHON) scripts/create_default_content_pages.py
+	$(PYTHON) scripts/seed/create_default_content_pages.py
 	@echo "Step 4/4: Creating platform pages and landing..."
-	$(PYTHON) scripts/create_platform_pages.py
+	$(PYTHON) scripts/seed/create_platform_pages.py
 	@echo "✅ Production initialization completed"
 ```
 
@@ -85,13 +85,13 @@ Now properly re-initializes the platform after reset!
 ```makefile
 # Utility commands (usually not needed - init-prod handles these)
 create-cms-defaults:
-	$(PYTHON) scripts/create_default_content_pages.py
+	$(PYTHON) scripts/seed/create_default_content_pages.py
 
 create-platform-pages:
-	$(PYTHON) scripts/create_platform_pages.py
+	$(PYTHON) scripts/seed/create_platform_pages.py
 
 init-logging:
-	$(PYTHON) scripts/init_log_settings.py
+	$(PYTHON) scripts/seed/init_log_settings.py
 ```
 
 These are now available for advanced use cases or re-running specific steps.
diff --git a/docs/development/migration/module-autodiscovery-migration.md b/docs/development/migration/module-autodiscovery-migration.md
index 7cf9666a..f9de169b 100644
--- a/docs/development/migration/module-autodiscovery-migration.md
+++ b/docs/development/migration/module-autodiscovery-migration.md
@@ -242,14 +242,14 @@ store_router.include_router(store_feature1_router, tags=["store-feature1"])
 Run architecture validation to check compliance:
 
 ```bash
-python scripts/validate_architecture.py
+python scripts/validate/validate_architecture.py
 ```
 
 Check for legacy location violations:
 
 ```bash
-python scripts/validate_architecture.py -d app/api/v1/store
-python scripts/validate_architecture.py -d app/services
+python scripts/validate/validate_architecture.py -d app/api/v1/store
+python scripts/validate/validate_architecture.py -d app/services
 ```
 
 Verify route count:
diff --git a/docs/development/migration/svc-006-migration-plan.md b/docs/development/migration/svc-006-migration-plan.md
index dbcd9acc..9ece8571 100644
--- a/docs/development/migration/svc-006-migration-plan.md
+++ b/docs/development/migration/svc-006-migration-plan.md
@@ -177,7 +177,7 @@ return SomeResponse(...)
 grep -n "db.commit()" app/services/<service_name>.py
 
 # Run architecture validator
-python scripts/validate_architecture.py -o <entity_name>
+python scripts/validate/validate_architecture.py -o <entity_name>
 
 # Run tests
 pytest tests/test_<service_name>.py -v
@@ -230,7 +230,7 @@ If issues are found after migration:
 
 Run this command to check remaining violations:
 ```bash
-python scripts/validate_architecture.py 2>&1 | grep "SVC-006" | wc -l
+python scripts/validate/validate_architecture.py 2>&1 | grep "SVC-006" | wc -l
 ```
 
 Current status: **60 remaining** (down from 66)
@@ -253,14 +253,14 @@ The SVC-006 rule is set to **warning** (not error), so CI won't fail. This allow
 
 ```bash
 # Count remaining violations
-python scripts/validate_architecture.py 2>&1 | grep "SVC-006" | wc -l
+python scripts/validate/validate_architecture.py 2>&1 | grep "SVC-006" | wc -l
 
 # List services with commits (sorted by count)
 grep -c "db.commit()" app/services/*.py | grep -v ":0$" | sort -t: -k2 -n
 
 # Validate specific entity
-python scripts/validate_architecture.py -o store
+python scripts/validate/validate_architecture.py -o store
 
 # Validate specific file
-python scripts/validate_architecture.py -f app/services/admin_service.py
+python scripts/validate/validate_architecture.py -f app/services/admin_service.py
 ```
diff --git a/docs/development/performance-rules.md b/docs/development/performance-rules.md
index 6771d7ef..9f7f1a25 100644
--- a/docs/development/performance-rules.md
+++ b/docs/development/performance-rules.md
@@ -1,6 +1,6 @@
 # Performance Rules Reference
 
-This document provides a comprehensive reference for all performance rules enforced by the `scripts/validate_performance.py` validator.
+This document provides a comprehensive reference for all performance rules enforced by the `scripts/validate/validate_performance.py` validator.
 
 ## Overview
 
@@ -16,26 +16,26 @@ The performance validator identifies potential performance issues and enforces b
 
 ```bash
 # Check all files
-python scripts/validate_performance.py
+python scripts/validate/validate_performance.py
 
 # Verbose output
-python scripts/validate_performance.py -v
+python scripts/validate/validate_performance.py -v
 
 # Errors only
-python scripts/validate_performance.py --errors-only
+python scripts/validate/validate_performance.py --errors-only
 
 # JSON output (for CI/CD)
-python scripts/validate_performance.py --json
+python scripts/validate/validate_performance.py --json
 ```
 
 ### Using the Unified Validator
 
 ```bash
 # Run performance checks only
-python scripts/validate_all.py --performance
+python scripts/validate/validate_all.py --performance
 
 # Run all validators
-python scripts/validate_all.py
+python scripts/validate/validate_all.py
 ```
 
 ## Severity Levels
diff --git a/docs/development/security-rules.md b/docs/development/security-rules.md
index 4b7ec185..00d0bd94 100644
--- a/docs/development/security-rules.md
+++ b/docs/development/security-rules.md
@@ -1,6 +1,6 @@
 # Security Rules Reference
 
-This document provides a comprehensive reference for all security rules enforced by the `scripts/validate_security.py` validator.
+This document provides a comprehensive reference for all security rules enforced by the `scripts/validate/validate_security.py` validator.
 
 ## Overview
 
@@ -16,26 +16,26 @@ The security validator identifies potential security vulnerabilities and enforce
 
 ```bash
 # Check all files
-python scripts/validate_security.py
+python scripts/validate/validate_security.py
 
 # Verbose output
-python scripts/validate_security.py -v
+python scripts/validate/validate_security.py -v
 
 # Errors only
-python scripts/validate_security.py --errors-only
+python scripts/validate/validate_security.py --errors-only
 
 # JSON output (for CI/CD)
-python scripts/validate_security.py --json
+python scripts/validate/validate_security.py --json
 ```
 
 ### Using the Unified Validator
 
 ```bash
 # Run security checks only
-python scripts/validate_all.py --security
+python scripts/validate/validate_all.py --security
 
 # Run all validators
-python scripts/validate_all.py
+python scripts/validate/validate_all.py
 ```
 
 ## Severity Levels
diff --git a/docs/development/seed-scripts-audit.md b/docs/development/seed-scripts-audit.md
index 1de23424..32413837 100644
--- a/docs/development/seed-scripts-audit.md
+++ b/docs/development/seed-scripts-audit.md
@@ -113,14 +113,14 @@ python scripts/utils/create_landing_page.py [store_subdomain]
 ```makefile
 # Full setup with inventory
 seed-demo-full:
-	$(PYTHON) scripts/seed_demo.py --include-inventory --include-landing
+	$(PYTHON) scripts/seed/seed_demo.py --include-inventory --include-landing
 
 # Utility commands (if keeping separate)
 create-inventory:
 	$(PYTHON) scripts/create_inventory.py
 
 init-logging:
-	$(PYTHON) scripts/init_log_settings.py
+	$(PYTHON) scripts/seed/init_log_settings.py
 ```
 
 ## 📋 Recommended File Structure
@@ -185,9 +185,9 @@ scripts/
 
 7. 📝 **Add --options to seed_demo.py**
    ```bash
-   python scripts/seed_demo.py --skip-inventory
-   python scripts/seed_demo.py --minimal
-   python scripts/seed_demo.py --help
+   python scripts/seed/seed_demo.py --skip-inventory
+   python scripts/seed/seed_demo.py --minimal
+   python scripts/seed/seed_demo.py --help
    ```
 
 ## 🚀 Expected Result After Refactoring
diff --git a/docs/features/cms-implementation-guide.md b/docs/features/cms-implementation-guide.md
index a36181e2..4a335f8d 100644
--- a/docs/features/cms-implementation-guide.md
+++ b/docs/features/cms-implementation-guide.md
@@ -217,7 +217,7 @@ Then update the footer template:
 
 ### 7. Create Default Platform Pages (Script)
 
-Create `scripts/create_default_content_pages.py`:
+Create `scripts/seed/create_default_content_pages.py`:
 
 ```python
 #!/usr/bin/env python3
@@ -347,7 +347,7 @@ if __name__ == "__main__":
 
 Run it:
 ```bash
-python scripts/create_default_content_pages.py
+python scripts/seed/create_default_content_pages.py
 ```
 
 ## Testing
diff --git a/docs/features/content-management-system.md b/docs/features/content-management-system.md
index 28a412ad..a16ba3c2 100644
--- a/docs/features/content-management-system.md
+++ b/docs/features/content-management-system.md
@@ -505,7 +505,7 @@ Standard slugs to implement:
 
 1. **Create Platform Defaults**:
 ```bash
-python scripts/create_default_content_pages.py
+python scripts/seed/create_default_content_pages.py
 ```
 
 2. **Migrate Existing Static Templates**:
diff --git a/docs/features/email-system.md b/docs/features/email-system.md
index b168087a..ffad525d 100644
--- a/docs/features/email-system.md
+++ b/docs/features/email-system.md
@@ -171,7 +171,7 @@ Templates use Jinja2 syntax for variable interpolation:
 Run the seed script to populate default templates:
 
 ```bash
-python scripts/seed_email_templates.py
+python scripts/seed/seed_email_templates.py
 ```
 
 This creates templates for:
@@ -302,7 +302,7 @@ Test coverage includes:
 app/services/email_service.py    # Email service with provider abstraction
 models/database/email.py         # EmailTemplate and EmailLog models
 app/core/config.py               # Email configuration settings
-scripts/seed_email_templates.py  # Template seeding script
+scripts/seed/seed_email_templates.py  # Template seeding script
 ```
 
 ### Provider Abstraction
diff --git a/docs/features/platform-homepage.md b/docs/features/platform-homepage.md
index 5f522a36..9b434239 100644
--- a/docs/features/platform-homepage.md
+++ b/docs/features/platform-homepage.md
@@ -193,7 +193,7 @@ Manage all platform content pages from a single interface:
 
 ```bash
 # Create all default platform pages
-python scripts/create_platform_pages.py
+python scripts/seed/create_platform_pages.py
 ```
 
 This creates:
@@ -568,7 +568,7 @@ return templates.TemplateResponse(
 **Solutions:**
 1. Run seeder script:
    ```bash
-   python scripts/create_platform_pages.py
+   python scripts/seed/create_platform_pages.py
    ```
 
 2. Verify page exists:
diff --git a/docs/getting-started/platform-homepage-quick-start.md b/docs/getting-started/platform-homepage-quick-start.md
index 8d409921..eb0ed0a4 100644
--- a/docs/getting-started/platform-homepage-quick-start.md
+++ b/docs/getting-started/platform-homepage-quick-start.md
@@ -11,7 +11,7 @@ Quick reference for setting up and customizing the platform homepage and content
 Run the seeder script to create all default platform pages:
 
 ```bash
-python scripts/create_platform_pages.py
+python scripts/seed/create_platform_pages.py
 ```
 
 This creates:
@@ -253,7 +253,7 @@ Result in header: `About | FAQ | Contact`
 
 **Fix:** Run seeder script
 ```bash
-python scripts/create_platform_pages.py
+python scripts/seed/create_platform_pages.py
 ```
 
 ### Navigation menu is empty
diff --git a/docs/implementation/email-settings.md b/docs/implementation/email-settings.md
index 4f6e218b..c2fbd149 100644
--- a/docs/implementation/email-settings.md
+++ b/docs/implementation/email-settings.md
@@ -296,7 +296,7 @@ Tests:
 - `alembic/versions/v0a1b2c3d4e5_add_store_email_settings.py` - Migration
 - `app/services/store_email_settings_service.py` - Service
 - `app/api/v1/store/email_settings.py` - API endpoints
-- `scripts/install.py` - Installation wizard
+- `scripts/seed/install.py` - Installation wizard
 
 ### Modified Files
 - `app/services/email_service.py` - Added platform config, store providers
diff --git a/docs/implementation/email-templates-architecture.md b/docs/implementation/email-templates-architecture.md
index 6bb5d4e2..e4356c7f 100644
--- a/docs/implementation/email-templates-architecture.md
+++ b/docs/implementation/email-templates-architecture.md
@@ -329,11 +329,11 @@ The migration:
 
 ## Seeding Templates
 
-**File:** `scripts/seed_email_templates.py`
+**File:** `scripts/seed/seed_email_templates.py`
 
 Run seed script:
 ```bash
-python scripts/seed_email_templates.py
+python scripts/seed/seed_email_templates.py
 ```
 
 The script:
diff --git a/docs/proposals/SESSION_NOTE_2026-02-09_import002-cross-module-deps.md b/docs/proposals/SESSION_NOTE_2026-02-09_import002-cross-module-deps.md
index 9692d914..a42ae4aa 100644
--- a/docs/proposals/SESSION_NOTE_2026-02-09_import002-cross-module-deps.md
+++ b/docs/proposals/SESSION_NOTE_2026-02-09_import002-cross-module-deps.md
@@ -228,12 +228,12 @@ Remaining 13 warnings require provider pattern refactoring. To be tackled in a f
 
 Current state:
 ```
-$ python scripts/validate_architecture.py
+$ python scripts/validate/validate_architecture.py
 → 0 errors, 13 warnings (all IMPORT-002 — provider pattern candidates)
 ```
 
 After Part B complete:
 ```
-$ python scripts/validate_architecture.py
+$ python scripts/validate/validate_architecture.py
 → 0 errors, 0 warnings
 ```
diff --git a/docs/proposals/decouple-modules-implementation-plan.md b/docs/proposals/decouple-modules-implementation-plan.md
index bba59e84..9cf43dd6 100644
--- a/docs/proposals/decouple-modules-implementation-plan.md
+++ b/docs/proposals/decouple-modules-implementation-plan.md
@@ -538,7 +538,7 @@ grep -r "from app.modules.orders" app/modules/core/ app/modules/tenancy/ app/mod
 # This would be a more advanced test
 
 # Run architecture validator
-python scripts/validate_architecture.py
+python scripts/validate/validate_architecture.py
 ```
 
 ---
diff --git a/docs/proposals/plan-perms.md b/docs/proposals/plan-perms.md
index ec1f4d0a..5445d6f1 100644
--- a/docs/proposals/plan-perms.md
+++ b/docs/proposals/plan-perms.md
@@ -590,7 +590,7 @@ ADD COLUMN is_custom BOOLEAN DEFAULT FALSE;
 
 2. **Migrations run:** `make migrate-up`
 
-3. **Architecture validation:** `python scripts/validate_architecture.py -v`
+3. **Architecture validation:** `python scripts/validate/validate_architecture.py -v`
 
 4. **Unit tests:** Test permission filtering logic
    - Platform with no config → all permissions allowed
diff --git a/scripts/README.md b/scripts/README.md
index aa8f39e4..8af525d2 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -21,19 +21,19 @@ This directory contains scripts for validating and enforcing architectural patte
 
 ```bash
 # Validate entire codebase
-python scripts/validate_architecture.py
+python scripts/validate/validate_architecture.py
 
 # Validate specific directory
-python scripts/validate_architecture.py app/api/
+python scripts/validate/validate_architecture.py app/api/
 
 # Verbose output with code context
-python scripts/validate_architecture.py --verbose
+python scripts/validate/validate_architecture.py --verbose
 
 # Show only errors (suppress warnings)
-python scripts/validate_architecture.py --errors-only
+python scripts/validate/validate_architecture.py --errors-only
 
 # Use custom config file
-python scripts/validate_architecture.py --config custom-rules.yaml
+python scripts/validate/validate_architecture.py --config custom-rules.yaml
 ```
 
 ### Exit Codes
@@ -175,7 +175,7 @@ jobs:
 
       - name: Validate Architecture
         run: |
-          python scripts/validate_architecture.py
+          python scripts/validate/validate_architecture.py
 ```
 
 ### Documentation
@@ -192,7 +192,7 @@ To add new rules:
 1. Add rule definition to `.architecture-rules.yaml`
 2. Implement validation logic in `validate_architecture.py`
 3. Add examples to `docs/architecture/architecture-patterns.md`
-4. Test with `python scripts/validate_architecture.py --verbose`
+4. Test with `python scripts/validate/validate_architecture.py --verbose`
 
 ### Troubleshooting
 
diff --git a/scripts/backup_database.py b/scripts/seed/backup_database.py
similarity index 100%
rename from scripts/backup_database.py
rename to scripts/seed/backup_database.py
diff --git a/scripts/create_default_content_pages.py b/scripts/seed/create_default_content_pages.py
similarity index 100%
rename from scripts/create_default_content_pages.py
rename to scripts/seed/create_default_content_pages.py
diff --git a/scripts/create_platform_pages.py b/scripts/seed/create_platform_pages.py
similarity index 100%
rename from scripts/create_platform_pages.py
rename to scripts/seed/create_platform_pages.py
diff --git a/scripts/init_db.py b/scripts/seed/init_db.py
similarity index 100%
rename from scripts/init_db.py
rename to scripts/seed/init_db.py
diff --git a/scripts/init_log_settings.py b/scripts/seed/init_log_settings.py
similarity index 100%
rename from scripts/init_log_settings.py
rename to scripts/seed/init_log_settings.py
diff --git a/scripts/init_production.py b/scripts/seed/init_production.py
similarity index 100%
rename from scripts/init_production.py
rename to scripts/seed/init_production.py
diff --git a/scripts/install.py b/scripts/seed/install.py
similarity index 100%
rename from scripts/install.py
rename to scripts/seed/install.py
diff --git a/scripts/seed_demo.py b/scripts/seed/seed_demo.py
similarity index 100%
rename from scripts/seed_demo.py
rename to scripts/seed/seed_demo.py
diff --git a/scripts/seed_email_templates.py b/scripts/seed/seed_email_templates.py
similarity index 100%
rename from scripts/seed_email_templates.py
rename to scripts/seed/seed_email_templates.py
diff --git a/scripts/base_validator.py b/scripts/validate/base_validator.py
similarity index 100%
rename from scripts/base_validator.py
rename to scripts/validate/base_validator.py
diff --git a/scripts/validate_all.py b/scripts/validate/validate_all.py
similarity index 91%
rename from scripts/validate_all.py
rename to scripts/validate/validate_all.py
index 1fc89dc5..7356a6fa 100755
--- a/scripts/validate_all.py
+++ b/scripts/validate/validate_all.py
@@ -8,14 +8,14 @@ This provides a single entry point for comprehensive code validation,
 useful for CI/CD pipelines and pre-commit hooks.
 
 Usage:
-    python scripts/validate_all.py                    # Run all validators
-    python scripts/validate_all.py --security        # Run only security validator
-    python scripts/validate_all.py --performance     # Run only performance validator
-    python scripts/validate_all.py --architecture    # Run only architecture validator
-    python scripts/validate_all.py --audit           # Run only audit validator
-    python scripts/validate_all.py -v                # Verbose output
-    python scripts/validate_all.py --fail-fast       # Stop on first failure
-    python scripts/validate_all.py --json            # JSON output
+    python scripts/validate/validate_all.py                    # Run all validators
+    python scripts/validate/validate_all.py --security        # Run only security validator
+    python scripts/validate/validate_all.py --performance     # Run only performance validator
+    python scripts/validate/validate_all.py --architecture    # Run only architecture validator
+    python scripts/validate/validate_all.py --audit           # Run only audit validator
+    python scripts/validate/validate_all.py -v                # Verbose output
+    python scripts/validate/validate_all.py --fail-fast       # Stop on first failure
+    python scripts/validate/validate_all.py --json            # JSON output
 
 Options:
     --architecture      Run architecture validator
@@ -41,8 +41,7 @@ def run_architecture_validator(verbose: bool = False) -> tuple[int, dict]:
     """Run the architecture validator"""
     try:
         # Import dynamically to avoid circular imports
-        sys.path.insert(0, str(Path(__file__).parent.parent))
-        from scripts.validate_architecture import ArchitectureValidator
+        from validate_architecture import ArchitectureValidator
 
         config_path = Path.cwd() / ".architecture-rules.yaml"
         validator = ArchitectureValidator(config_path=config_path, verbose=verbose)
diff --git a/scripts/validate_architecture.py b/scripts/validate/validate_architecture.py
similarity index 99%
rename from scripts/validate_architecture.py
rename to scripts/validate/validate_architecture.py
index bc5cd82e..7f23c332 100755
--- a/scripts/validate_architecture.py
+++ b/scripts/validate/validate_architecture.py
@@ -12,12 +12,12 @@ This script checks that the codebase follows key architectural decisions:
 - API endpoint patterns
 
 Usage:
-    python scripts/validate_architecture.py                           # Check all files in current directory
-    python scripts/validate_architecture.py -d app/api/               # Check specific directory
-    python scripts/validate_architecture.py -f app/api/v1/stores.py  # Check single file
-    python scripts/validate_architecture.py -o merchant                # Check all merchant-related files
-    python scripts/validate_architecture.py -o store --verbose       # Check store files with details
-    python scripts/validate_architecture.py --json                    # JSON output
+    python scripts/validate/validate_architecture.py                           # Check all files in current directory
+    python scripts/validate/validate_architecture.py -d app/api/               # Check specific directory
+    python scripts/validate/validate_architecture.py -f app/api/v1/stores.py  # Check single file
+    python scripts/validate/validate_architecture.py -o merchant                # Check all merchant-related files
+    python scripts/validate/validate_architecture.py -o store --verbose       # Check store files with details
+    python scripts/validate/validate_architecture.py --json                    # JSON output
 
 Options:
     -f, --file PATH       Validate a single file (.py, .js, or .html)
diff --git a/scripts/validate_audit.py b/scripts/validate/validate_audit.py
similarity index 99%
rename from scripts/validate_audit.py
rename to scripts/validate/validate_audit.py
index 9b0884e9..993230a7 100644
--- a/scripts/validate_audit.py
+++ b/scripts/validate/validate_audit.py
@@ -11,10 +11,10 @@ import sys
 from pathlib import Path
 
 
-# Add project root to path
-sys.path.insert(0, str(Path(__file__).parent.parent))
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent))
 
-from scripts.base_validator import BaseValidator
+from base_validator import BaseValidator
 
 
 class AuditValidator(BaseValidator):
diff --git a/scripts/validate_performance.py b/scripts/validate/validate_performance.py
similarity index 98%
rename from scripts/validate_performance.py
rename to scripts/validate/validate_performance.py
index b8081ac5..e828a15f 100755
--- a/scripts/validate_performance.py
+++ b/scripts/validate/validate_performance.py
@@ -13,12 +13,12 @@ This script checks for common performance issues:
 - Missing timeouts and connection pooling
 
 Usage:
-    python scripts/validate_performance.py                           # Check all files
-    python scripts/validate_performance.py -d app/services/          # Check specific directory
-    python scripts/validate_performance.py -f app/api/v1/products.py # Check single file
-    python scripts/validate_performance.py -v                        # Verbose output
-    python scripts/validate_performance.py --json                    # JSON output
-    python scripts/validate_performance.py --errors-only             # Only show errors
+    python scripts/validate/validate_performance.py                           # Check all files
+    python scripts/validate/validate_performance.py -d app/services/          # Check specific directory
+    python scripts/validate/validate_performance.py -f app/api/v1/products.py # Check single file
+    python scripts/validate/validate_performance.py -v                        # Verbose output
+    python scripts/validate/validate_performance.py --json                    # JSON output
+    python scripts/validate/validate_performance.py --errors-only             # Only show errors
 
 Options:
     -f, --file PATH       Validate a single file
diff --git a/scripts/validate_security.py b/scripts/validate/validate_security.py
similarity index 98%
rename from scripts/validate_security.py
rename to scripts/validate/validate_security.py
index 3a89f58f..a75c8d54 100755
--- a/scripts/validate_security.py
+++ b/scripts/validate/validate_security.py
@@ -14,12 +14,12 @@ This script checks for common security vulnerabilities:
 - Data exposure risks
 
 Usage:
-    python scripts/validate_security.py                           # Check all files
-    python scripts/validate_security.py -d app/api/               # Check specific directory
-    python scripts/validate_security.py -f app/api/v1/auth.py     # Check single file
-    python scripts/validate_security.py -v                        # Verbose output
-    python scripts/validate_security.py --json                    # JSON output
-    python scripts/validate_security.py --errors-only             # Only show errors
+    python scripts/validate/validate_security.py                           # Check all files
+    python scripts/validate/validate_security.py -d app/api/               # Check specific directory
+    python scripts/validate/validate_security.py -f app/api/v1/auth.py     # Check single file
+    python scripts/validate/validate_security.py -v                        # Verbose output
+    python scripts/validate/validate_security.py --json                    # JSON output
+    python scripts/validate/validate_security.py --errors-only             # Only show errors
 
 Options:
     -f, --file PATH       Validate a single file
diff --git a/scripts/validators/__init__.py b/scripts/validate/validators/__init__.py
similarity index 100%
rename from scripts/validators/__init__.py
rename to scripts/validate/validators/__init__.py
diff --git a/scripts/validators/base.py b/scripts/validate/validators/base.py
similarity index 100%
rename from scripts/validators/base.py
rename to scripts/validate/validators/base.py
diff --git a/scripts/verify_critical_imports.py b/scripts/validate/verify_critical_imports.py
similarity index 100%
rename from scripts/verify_critical_imports.py
rename to scripts/validate/verify_critical_imports.py