orion/docs/development/seed-scripts-audit.md

Seed Scripts Audit & Refactoring Plan

Date: 2025-12-01 Status: ✅ REFACTORING COMPLETE

Implementation: See makefile-refactoring-complete.md for details

Current State Analysis

📊 Inventory of Seed Scripts

Script	Purpose	In Makefile?	Issues
seed_demo.py	Create merchants, stores, customers, products	✅ Yes	❌ Missing inventory creation
create_default_content_pages.py	Create platform CMS pages (about, faq, etc.)	✅ Yes (create-cms-defaults)	✅ Good
create_inventory.py	Create inventory for products	❌ NO	⚠️ Should be in seed_demo
create_landing_page.py	Create landing pages for stores	❌ NO	⚠️ Should be in seed_demo
create_platform_pages.py	Create platform pages	❌ NO	🔴 DUPLICATE of create_default_content_pages
init_production.py	Create admin user + platform alerts	✅ Yes (init-prod)	✅ Good
init_log_settings.py	Initialize log settings	❌ NO	⚠️ Should be in init_production?

🎯 Intended Database Setup Flow (from Makefile)

make db-setup
  ↓
1. migrate-up              # Run Alembic migrations
2. init-prod              # Create admin user + alerts
3. create-cms-defaults    # Create default content pages
4. seed-demo              # Create demo merchants/stores/data

🔴 Problems Identified

1. Missing Functionality in seed_demo.py

seed_demo.py creates products but NOT inventory:

• ❌ Products are created without inventory records
• ❌ Stores can't manage stock
• ❌ Separate create_inventory.py script exists but not integrated

2. Duplicate Scripts

• create_platform_pages.py duplicates create_default_content_pages.py
• Both create platform-level content pages
• Causes confusion about which to use

3. Orphaned Scripts (Not in Makefile)

Scripts that exist but aren't part of the standard workflow:

• create_inventory.py - Should be integrated into seed_demo
• create_landing_page.py - Should be integrated into seed_demo
• create_platform_pages.py - Should be deleted (duplicate)
• init_log_settings.py - Should be in init_production or separate command

4. Missing Landing Pages in seed_demo

The seed creates stores but not their landing pages:

• Stores have no homepage
• Manual script required (create_landing_page.py)
• Should be automatic in demo seeding

✅ Proposed Refactoring Plan

Phase 1: Consolidate seed_demo.py (HIGH PRIORITY)

Update seed_demo.py to include:

def seed_demo_data(db: Session, auth_manager: AuthManager):
    # Step 1-3: Existing (environment, admin, reset)
    # Step 4: Create merchants ✅ DONE
    # Step 5: Create stores ✅ DONE
    # Step 6: Create customers ✅ DONE
    # Step 7: Create products ✅ DONE
    # Step 8: Create inventory ❌ ADD THIS
    # Step 9: Create landing pages ❌ ADD THIS

Benefits:

• ✅ One command seeds everything
• ✅ Consistent demo environment
• ✅ Stores immediately usable

Phase 2: Clean Up Duplicate Scripts

Delete:

• ❌ create_platform_pages.py (duplicate of create_default_content_pages.py)

Keep:

• ✅ create_default_content_pages.py (used in Makefile)

Phase 3: Integrate or Document Orphaned Scripts

Option A: Integrate into seed_demo

# In seed_demo.py
def create_demo_inventory(db, stores):
    """Create inventory for all products"""
    # Move logic from create_inventory.py

def create_demo_landing_pages(db, stores):
    """Create landing pages for stores"""
    # Move logic from create_landing_page.py

Option B: Make them utility scripts Move to scripts/utils/ and document:

# For one-off tasks
python scripts/utils/create_inventory.py
python scripts/utils/create_landing_page.py [store_subdomain]

Phase 4: Update Makefile

Add new commands:

# Full setup with inventory
seed-demo-full:
	$(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/seed/init_log_settings.py

📋 Recommended File Structure

scripts/
├── Core Setup (Run in Order)
│   ├── init_production.py       # 1. Create admin + platform config
│   ├── init_log_settings.py     # 2. Configure logging (or merge into init_production)
│   └── seed_demo.py              # 3. Seed demo data (EVERYTHING)
│
├── CMS Setup
│   └── create_default_content_pages.py  # Platform CMS defaults
│
├── Utilities (One-off/Manual)
│   ├── create_inventory.py      # ⚠️ Should be in seed_demo
│   ├── create_landing_page.py   # ⚠️ Should be in seed_demo
│   ├── backup_database.py
│   └── verify_setup.py
│
├── Testing
│   ├── test_auth_complete.py
│   ├── test_store_management.py
│   └── test_logging_system.py
│
├── Diagnostics
│   ├── route_diagnostics.py
│   ├── show_structure.py
│   └── validate_architecture.py
│
└── TO DELETE
    └── create_platform_pages.py  # 🔴 DUPLICATE

🎯 Implementation Priority

Immediate (Do Now)

1. ✅ Add inventory creation to seed_demo.py

   • Move logic from create_inventory.py
   • Create create_demo_inventory() function

2. ✅ Add landing page creation to seed_demo.py

   • Move logic from create_landing_page.py
   • Create create_demo_landing_pages() function

3. ❌ Delete create_platform_pages.py

   • It's a duplicate

Soon (This Week)

4. ⚠️ Decide on init_log_settings.py

   • Merge into init_production.py, OR
   • Add to Makefile as separate step

5. ⚠️ Update Makefile documentation

   • Document all seed commands
   • Update help text

Later (Nice to Have)

6. 📝 Create scripts/utils/ directory

   • Move utility scripts
   • Update documentation

7. 📝 Add --options to seed_demo.py

   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

Single Command Setup:

# Developer onboarding
make db-setup

# What happens:
# 1. ✅ Migrations applied
# 2. ✅ Admin user created
# 3. ✅ Platform CMS pages created
# 4. ✅ 3 demo merchants created
# 5. ✅ 3 demo stores created (1 per merchant)
# 6. ✅ 15 customers per store
# 7. ✅ 20 products per store
# 8. ✅ Inventory for all products ← NEW
# 9. ✅ Landing pages for all stores ← NEW
# 10. ✅ Ready to code!

Result:

• 🎯 Consistent, reproducible demo environment
• 🎯 No manual steps required
• 🎯 New developers up and running in seconds
• 🎯 All features immediately testable

📝 Questions to Answer

1. Should init_log_settings be part of init_production?

   • Pro: One less manual step
   • Con: Logging is separate concern

2. Keep create_inventory.py as utility or delete?

   • If integrated into seed_demo, do we need the standalone script?
   • Use case: Fix inventory for existing stores?

3. Keep create_landing_page.py as utility or delete?

   • If integrated into seed_demo, do we need the standalone script?
   • Use case: Create landing page for new store post-seed?

🎬 Next Actions

• Review this audit with team
• Decide on orphaned scripts
• Implement Phase 1 (add inventory + landing to seed_demo)
• Delete create_platform_pages.py
• Update Makefile
• Update developer documentation