thrillwiki_django_no_react/shared/docs/memory-bank/projects/company-migration-plan.md

Company Migration Implementation Plan

Date: 2025-07-04
Status: 📋 PLANNING COMPLETE
Risk Level: 🔴 HIGH
Dependencies: company-migration-analysis.md

Migration Strategy Overview

This document outlines the detailed 4-phase migration strategy to safely remove the Company entity and replace it with the new relationship structure (Operators, PropertyOwners, Manufacturers, Designers) across the ThrillWiki Django application.

Phase-by-Phase Implementation Plan

Phase 1: Create New Entities 🏗️

Duration: 2-3 days
Risk Level: 🟡 LOW
Rollback: Simple (new entities can be removed)

1.1 Create New Models

# New models to create:
- Operators (replace Company.owner for parks)
- PropertyOwners (new optional relationship for parks)
- Manufacturers (rename/replace Company for rides)
- Designers (already exists, verify structure)

1.2 Database Schema Changes

• Create new model files
• Generate initial migrations
• Apply migrations to create new tables
• Verify new table structure

1.3 Admin Interface Setup

• Register new models in Django admin
• Configure admin interfaces for new entities
• Set up basic CRUD operations

1.4 Phase 1 Testing

• Verify new models can be created/edited
• Test admin interfaces
• Confirm database schema is correct
• Run existing test suite (should pass unchanged)

Phase 2: Data Migration 📊

Duration: 3-5 days
Risk Level: 🔴 HIGH
Rollback: Complex (requires data restoration)

2.1 Data Analysis & Mapping

-- Analyze existing company data:
SELECT 
    company_type,
    COUNT(*) as count,
    usage_context
FROM companies_company 
GROUP BY company_type;

2.2 Data Migration Scripts

• Company → Operators: Migrate companies used as park owners
• Company → Manufacturers: Migrate companies used as ride manufacturers
• PropertyOwners = Operators: Initially set PropertyOwners same as Operators
• Historical Data: Migrate pghistory tracking data

2.3 Data Migration Execution

# Critical sequence:
1. uv run manage.py makemigrations --dry-run  # Preview changes
2. Database backup (MANDATORY)
3. uv run manage.py migrate  # Apply data migration
4. Verify data integrity
5. Test rollback procedures

2.4 Data Integrity Verification

• Verify all company records migrated correctly
• Check foreign key relationships maintained
• Validate pghistory data preservation
• Confirm no data loss occurred

Phase 3: Update Dependencies 🔄

Duration: 5-7 days
Risk Level: 🟠 MEDIUM-HIGH
Rollback: Moderate (code changes can be reverted)

3.1 Models Update (Critical First)

Order: MUST be completed before views/templates

# parks/models.py updates:
- Replace: company = ForeignKey(Company)
- With: operator = ForeignKey(Operators)
- Add: property_owner = ForeignKey(PropertyOwners, null=True, blank=True)

# rides/models.py updates:
- Replace: company = ForeignKey(Company) 
- With: manufacturer = ForeignKey(Manufacturers, null=True, blank=True)

3.2 Views Update

Dependencies: Models must be updated first

• Update all company-related views
• Modify query logic for new relationships
• Update context data for templates
• Handle new optional relationships

3.3 Templates Update

Dependencies: Views must be updated first

• Update 6+ company templates
• Modify cross-references in park/ride templates
• Update form templates for new relationships
• Ensure responsive design maintained

3.4 Tests Update

Dependencies: Models/Views/Templates updated first

• Update 429 lines of company tests
• Modify integration tests
• Update test fixtures and factories
• Add tests for new relationships

3.5 Signals & Search Update

• Update Django signals for new models
• Modify search indexing for new relationships
• Update search templates and views
• Verify search functionality

3.6 Admin Interface Update

• Update admin configurations
• Modify admin templates if customized
• Update admin permissions
• Test admin functionality

Phase 4: Cleanup 🧹

Duration: 2-3 days
Risk Level: 🟡 LOW-MEDIUM
Rollback: Difficult (requires restoration of removed code)

4.1 Remove Companies App

• Remove companies/ directory
• Remove from INSTALLED_APPS
• Remove URL patterns
• Remove imports across codebase

4.2 Remove Company Templates

• Remove templates/companies/ directory
• Remove company-related template tags
• Clean up cross-references
• Update template inheritance

4.3 Documentation Update

• Update API documentation
• Update user documentation
• Update developer documentation
• Update README if needed

4.4 Final Cleanup

• Remove unused imports
• Clean up migration files
• Update requirements if needed
• Final code review

Critical Order of Operations

⚠️ MANDATORY SEQUENCE ⚠️

1. Phase 1: Create new entities (safe, reversible)
2. Phase 2: Migrate data (HIGH RISK - backup required)
3. Phase 3: Update dependencies in order:
   a. Models FIRST (foreign keys)
   b. Views SECOND (query logic)
   c. Templates THIRD (display logic)
   d. Tests FOURTH (validation)
   e. Signals/Search FIFTH (integrations)
   f. Admin SIXTH (management interface)
4. Phase 4: Cleanup (remove old code)

🚫 NEVER DO THESE OUT OF ORDER:

• Never update views before models
• Never update templates before views
• Never remove Company model before data migration
• Never skip database backups
• Never proceed without testing previous phase

Database Schema Migration Strategy

New Relationship Structure

Current:
Parks → Company (owner)
Rides → Company (manufacturer)

Target:
Parks → Operators (required, replaces Company.owner)
Parks → PropertyOwners (optional, new concept)
Rides → Manufacturers (optional, replaces Company)
Rides → Designers (optional, exists)

Migration Script Approach

# Data migration pseudocode:
def migrate_companies_to_new_structure(apps, schema_editor):
    Company = apps.get_model('companies', 'Company')
    Operator = apps.get_model('operators', 'Operator')
    Manufacturer = apps.get_model('manufacturers', 'Manufacturer')
    
    # Migrate park owners
    for company in Company.objects.filter(used_as_park_owner=True):
        operator = Operator.objects.create(
            name=company.name,
            # ... other fields
        )
        # Update park references
    
    # Migrate ride manufacturers  
    for company in Company.objects.filter(used_as_manufacturer=True):
        manufacturer = Manufacturer.objects.create(
            name=company.name,
            # ... other fields
        )
        # Update ride references

Testing Strategy

Phase-by-Phase Testing

# After each phase:
1. uv run manage.py test  # Full test suite
2. Manual testing of affected functionality
3. Database integrity checks
4. Performance testing if needed
5. Rollback testing (Phase 2 especially)

Critical Test Areas

• Model Relationships: Foreign key integrity
• Data Migration: No data loss, correct mapping
• pghistory Integration: Historical data preserved
• Search Functionality: New relationships indexed
• Admin Interface: CRUD operations work
• Template Rendering: No broken references

Risk Mitigation Procedures

Database Safety Protocol

# MANDATORY before Phase 2:
1. pg_dump thrillwiki_db > backup_pre_migration.sql
2. Test restore procedure: psql thrillwiki_test < backup_pre_migration.sql
3. Document rollback steps
4. Verify backup integrity

Rollback Procedures

Phase 1 Rollback (Simple)

# Remove new models:
uv run manage.py migrate operators zero
uv run manage.py migrate manufacturers zero
# Remove from INSTALLED_APPS

Phase 2 Rollback (Complex)

# Restore from backup:
dropdb thrillwiki_db
createdb thrillwiki_db  
psql thrillwiki_db < backup_pre_migration.sql
# Verify data integrity

Phase 3 Rollback (Moderate)

# Revert code changes:
git revert <migration_commits>
uv run manage.py migrate  # Revert migrations
# Test functionality

Success Criteria

Phase 1 Success ✅

• New models created and functional
• Admin interfaces working
• Existing functionality unchanged
• All tests passing

Phase 2 Success ✅

• All company data migrated correctly
• No data loss detected
• pghistory data preserved
• Foreign key relationships intact
• Rollback procedures tested

Phase 3 Success ✅

• All 300+ company references updated
• New relationships functional
• Templates rendering correctly
• Search functionality working
• All tests updated and passing

Phase 4 Success ✅

• Companies app completely removed
• No broken references remaining
• Documentation updated
• Code cleanup completed

Timeline Estimate

Phase	Duration	Dependencies	Risk Level
Phase 1	2-3 days	None	🟡 LOW
Phase 2	3-5 days	Phase 1 complete	🔴 HIGH
Phase 3	5-7 days	Phase 2 complete	🟠 MEDIUM-HIGH
Phase 4	2-3 days	Phase 3 complete	🟡 LOW-MEDIUM
Total	12-18 days	Sequential execution	🔴 HIGH

Implementation Readiness

Prerequisites ✅

• Comprehensive analysis completed
• Migration plan documented
• Risk assessment completed
• Success criteria defined

Next Steps

• Set up dedicated migration environment
• Create detailed migration scripts
• Establish backup and monitoring procedures
• Begin Phase 1 implementation

Recommendation: Proceed with Phase 1 implementation in dedicated environment with comprehensive testing at each step.