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)

```bash
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:**
```python
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**
```python
# 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:
```bash
# 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:**
```makefile
# 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**
   ```bash
   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:**
```bash
# 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